In brief
- A skill adds reusable procedure and domain context without retraining the underlying model.
- The agent first sees only the name and description, loads SKILL.md for a matching task and accesses supporting files only as needed.
- A skill is neither a tool nor a permission boundary: access and actions still need technical enforcement.
- Versioning, provenance, evaluation and review of bundled scripts belong to a safe operational lifecycle.
What belongs in an Agent Skill?
The open Agent Skills format defines a folder as the basic unit. SKILL.md is required. It begins with metadata such as name and description and then contains the working instructions in Markdown. The description matters because a compatible agent uses it to assess which tasks may call for the skill.
A small skill can live entirely in SKILL.md. Larger skills move details into supporting files so that every use does not consume context with all available material.
- SKILL.md: metadata, scope, workflow, rules and examples
- scripts/: optional reusable programs for calculation, validation or file processing
- references/: optional domain rules, schemas or detailed documentation
- assets/: optional templates, images, sample files or other static resources
- Licence, compatibility information and additional metadata can further qualify use
How are skills discovered, activated and executed?
Skills use progressive disclosure. An agent can therefore know about many capabilities without loading all their instructions into its limited context window at once. The exact activation mechanism depends on the agent client implementing the format.
- Step 1
Discovery
The client initially exposes only the name and description of each available skill. This metadata should identify the task and activation conditions precisely.
- Step 2
Activation
When the current task matches the description, the agent loads the complete instructions from SKILL.md into context.
- Step 3
Execution
The agent follows the workflow and reads references, uses assets or runs scripts only where the instructions call for them in the current case.
- Step 4
Review
The application and accountable people assess the result, tool calls and permitted effects under the same quality and approval rules as other agent capabilities.
How do skills differ from other AI components?
These terms describe different layers. A skill may use prompts, tools or knowledge sources, but it does not replace them. A robust architecture keeps instruction, knowledge, interface, process logic and permission boundaries distinct.
| Component | Purpose | Difference from an Agent Skill |
|---|---|---|
| Prompt or system instruction | Directs model behaviour or a single task in the current context. | A skill packages reusable procedure with metadata and optional resources; its SKILL.md itself contains instructions. |
| Tool or function calling | Provides a callable function or controlled access to a system. | A skill can explain when and how to use a tool but provides neither the interface nor the permission. |
| MCP | Standardises how a client discovers and uses a server’s tools, resources and templates. | A skill packages procedural knowledge and local resources. It may use MCP tools but is not a connection protocol. |
| Workflow | Defines steps, transitions and controls mainly in software. | An agent interprets a skill according to the situation. Fixed process logic is usually better for deterministic or critical execution. |
| RAG or a knowledge format such as OKF | Supplies current knowledge or structures knowledge content for exchange and use. | A skill describes how to perform a task. Domain guidance may live in references, but authoritative and current data should come from governed sources. |
| Fine-tuning | Changes model behaviour through additional training. | A skill remains outside the model and is readable, replaceable and independently versioned. |
When is a skill useful, and when is a normal guide enough?
A skill is useful when a compatible agent should repeatedly perform a bounded procedure that needs more than a short instruction. Skills are particularly helpful when domain rules, templates or tested scripts should be maintained together and reused across projects or clients.
A normal instruction or template is often enough for a rare, simple task without supporting resources. A fully predictable process with serious consequences usually belongs in tested software or a fixed workflow rather than freely interpreted guidance.
- Useful: a repeated multi-step domain task with a clear definition of a good result
- Useful: shared review rules, templates or robust helper scripts need to be reusable
- Useful: the procedure should be documented and versioned independently of a chat
- A guide is enough: a short, infrequent task without files, execution or notable edge cases
- A workflow is better: sequence and outcome must be enforced deterministically or errors could have serious effects
How should organisations maintain and evaluate skills?
A skill is a maintainable software and knowledge artefact. It needs a domain owner, traceable provenance and a defined approval route. Changes to models, tools, policies or file formats can alter its behaviour even when SKILL.md itself has not changed.
- Step 1
Define purpose and ownership
Document the task, audience, permitted data, expected result and accountable domain team.
- Step 2
Record provenance and dependencies
Keep author, licence, sources, required tools, runtime and external packages traceable.
- Step 3
Evaluate with real cases
Test activation, non-activation, result quality, edge cases, tool use and safe stopping separately.
- Step 4
Version and release
Version the skill, references, assets and scripts together; review changes and pin an approved version where appropriate.
- Step 5
Monitor and retire
Track failures, outdated rules and dependencies and remove unsupported versions in a controlled manner.
Which permissions and security controls does a skill need?
An instruction in SKILL.md is not a technical security boundary. If a skill runs a script or uses a tool, the real filesystem, network and system permissions of that execution apply. Unreviewed skills can therefore create supply-chain risk much like third-party code, macros or packages.
A skill should use only the capabilities needed for its task. The executing application continues to constrain and validate critical actions and to require human approval where appropriate. Secrets do not belong in SKILL.md, bundled references, assets or scripts.
- Accept skills and updates only from traceable sources
- Review scripts, dependencies and installation steps before approval
- Limit file, network and tool permissions according to least privilege
- Treat inputs, outputs and downloaded content as potentially untrusted
- Log the skill version, relevant tool calls, results and approvals
- Run negative tests for false activation, manipulated references and disallowed actions
Example: a skill for preparing a tender response
An organisation creates a skill for recurring tenders. SKILL.md defines entry criteria, review steps and the expected dossier. references/ contains approved domain rules, assets/ provides a response template and scripts/validate-response.py checks mandatory fields and cross-references. For a matching request, the agent activates the skill, reads only the required references and retrieves approved product data through a controlled tool or MCP server. It produces a gap list and draft but sends nothing and invents no commitments. Domain owners review sources, exceptions and final approval.
What to remember
Use Agent Skills for bounded, repeated procedure with traceable resources. Treat every skill as a versioned, reviewable artefact, not as a shortcut for permissions, current knowledge sources or fixed process controls.
Sources and further reading
These primary sources provide further detail on definitions, technical foundations or responsible use.
Content reviewed