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.

No single system instruction guarantees protection. OWASP describes direct and indirect prompt injection as persistent risks. A skill therefore combines content labelling, permission boundaries, destination allowlists, data-flow rules, simulation for dangerous actions and human confirmation. Security comes from system design, not stern wording.

Versions change contracts

Skills evolve. Semantic Versioning offers a clear pattern: major signals incompatible contracts, minor adds compatible functionality and patch supplies compatible fixes. The number is useful only with a changelog describing impact, migration and renewed approval.

Each run binds a concrete skill and dependency version. „Always latest" undermines reproducibility. Releases pass tests, security review and staged rollout. Rollback must consider data changes already produced, not merely restore package files.

Skills are products with ownership

A skill needs a domain owner, technical maintainer and risk accountability. The owner validates method and edge cases. The maintainer keeps schemas, tools and tests operational. Risk accountability approves permissions and approval gates. One person may hold several roles, but decisions remain explicit.

A registry entry records purpose, version, state, owner, allowed environments, data classes, tools, dependencies, tests, last review and retirement date. Obsolete skills are disabled and linked to a successor instead of silently lingering.

Reuse needs parameters, not copies

Copied skills drift. A stable core with defined parameters and project policies is stronger. Yet a universal policy layer is also dangerous: law, language, risk and access differ by project. The skill states which values are configurable and which safety boundaries cannot be overridden.

Composition relies on contracts, not text concatenation. An orchestrator checks preconditions and postconditions, passes only necessary data and stops when an output does not satisfy the next contract. This preserves which skill prepared each decision.

Rollout needs an explicit error budget

A skill should begin in observation or simulation mode, then move to a small approved cohort before receiving broader authority. Teams define an error budget for false activation, invalid output, unintended tool use and unnecessary escalation. Exhausting that budget pauses expansion and triggers review. High-impact capabilities may retain permanent sampling even after release.

Operational readiness also includes ownership during failure. Alerts identify who responds, which evidence is preserved and how queued work is handled while the skill is disabled. A fallback procedure must be usable without the agent. This prevents automation from becoming the only surviving copy of a business method.

Method: EXTRACT → CONTRACT → BOUND → TEST → VERSION → OBSERVE → IMPROVE

EXTRACT makes decisions and exceptions explicit. CONTRACT defines input, output and failure. BOUND limits tools, data and impact. TEST covers ordinary, edge and adversarial cases. VERSION keeps contracts reproducible. OBSERVE captures minimal evidence. IMPROVE turns incidents and reviews into controlled change.

A skill is executable knowledge when another person can understand its intent, a system can validate its contracts, and an organisation can constrain and reconstruct its material effects.

Worksheet: Design a Skill Contract

1. Select a recurring method with a clear outcome and name its owner.

2. Document three successes, two failures and one ambiguous case.

3. Define activation, exclusions, input, output and failure states.

4. Assign minimum rights, destinations and runtime limits to each tool.

5. Write seven tests including permission denial and prompt injection.

6. Define evidence, quality metrics, approval gates and abort conditions.

7. Assign version, changelog, review date and retirement rule.

Reflection: Which expert decision remains invisible between two process steps? Which permission could be removed without defeating the skill's purpose?

All materials to download — the topic overview and the worksheet:

Scope: „Skill" denotes a product-independent executable knowledge package. Formats and runtimes differ across platforms. A skill is not automatically safe or professionally correct; permissions, tests, approvals and runtime controls remain necessary. Editorial and technical review: 17 July 2026.