Skills as executable knowledge

Organisations hold methods in checklists, guides, decision trees, templates and experience. As documents, they still require a person to find, interpret and adapt them. An AI agent can help, but a long prompt does not make a method reliable. Natural language alone does not strictly validate inputs, technically restrict permissions or test results reproducibly.

A skill closes this gap. It packages professional intent, activation conditions, input and output contracts, tool access, procedure, limits, tests and evidence as a versioned unit. The agent receives not merely more context but a controlled way to perform a capability. Knowledge becomes reusable, inspectable and consistent across projects.

A skill is more than a prompt

A prompt can state role, goal and desired format. It often does not establish whether a file exists, which schema data must satisfy, which operation may run, how failure is represented or which approval precedes a change.

A defensible skill therefore has four layers. The semantic layer explains purpose and domain logic. The contract layer defines inputs, outputs and errors. The operational layer binds tools, permissions and runtime limits. The assurance layer contains tests, quality criteria and evidence. Natural language remains important, but machine-readable rules and executable controls supplement it.

Tacit expertise becomes an explicit procedure

Experts skip many mental steps. They notice incomplete information, distinguish harmless variation from critical exception and know when to stop. Skill design must expose that tacit judgement. The ideal path is insufficient; boundaries, exclusions and escalation points matter.

Extraction starts from real cases: three successes, two failures and one ambiguous example. Record context, decision, evidence, action and expected outcome. Repeated patterns become rules; exceptions become stop or clarification conditions. The skill captures professional refusal as well as best practice.

The contract begins before execution

Every skill needs a clear entry. Which fields are required? Which types, ranges, formats and languages are valid? Which assumptions are forbidden? JSON Schema can describe and validate structured input. Files add type, size, checksum and sensitivity checks.

Output also has a contract. A report may require sections, sources, status and uncertainty. A data change may produce a patch rather than mutate production. Insufficient evidence returns needs_review rather than invented success. Failures become defined states such as invalid_input, permission_denied, tool_unavailable, quality_failed and approval_required.

Contracts enable composition. If skill A guarantees a validated manifest and skill B accepts that manifest, a workflow can connect them without guessing meaning between loose prose.

Activation is a professional decision

A skill should not run solely because its name resembles a request. It needs positive preconditions and explicit exclusions. A contract-review skill may require a complete document of a supported type while excluding legal decisions. A data-export skill may apply only to approved records and authorised destinations.

Activation records request, detected prerequisites, chosen version and rationale. High-impact use may require human confirmation. This prevents an agent from selecting a technically available but professionally inappropriate capability.

Tools are bound as constrained capabilities

A skill receives only tools required for its purpose. Reading, writing, deletion, execution and external transfer are separate permissions. A reporting skill may read files without deleting them. An import skill may write to staging but not directly to approved data.

Descriptions such as OpenAPI can define operations, parameters and responses in machine-readable form, but they do not authorise access. The skill also limits target systems, resources, duration, volume and failure handling. Credentials are obtained from a secure runtime store, never embedded in instructions.

Decisions need evidence, not plausible explanations

An agent can generate convincing reasons after an event. That is not proof of the path taken. Skills collect structured evidence: input revision, called tools, parameters, response status, produced artefacts, test results and approvals. W3C PROV offers the useful distinction among entities, activities and responsible agents.

Logging remains data-minimised. Not every input belongs in a permanent log. Sensitive material can be represented by references, hashes or redacted excerpts. The goal is traceability, not an uncontrolled secondary database.

Tests cover behaviour, boundaries and failure modes

A skill without tests is a claim. A minimum suite includes a normal case, boundaries, missing fields, contradictory data, unavailable tool, denied permission and prompt injection inside a read document. Domain gold cases specify expected decisions and prohibited actions.

Tests distinguish deterministic and probabilistic parts. Schema validation must remain stable. A summary may vary while satisfying source coverage, prohibited-claim and format criteria. Repeated runs measure variance. Model, tool and dependency changes trigger regression testing.

Evaluation asks more than whether the skill finished. It measures correctness, completeness, source binding, cost, latency, clarification rate, abort rate and false approvals. Critical errors carry more weight than style differences.

Prompt injection makes boundaries essential

Agents read content that may itself contain instructions: pages, messages, documents or tickets. That content must not override the skill contract. Architecture separates trusted control from untrusted content, minimises tools, validates outputs before follow-on actions and requires approval for irreversible steps.