What is Skill?
Skill, in the Agent Skills sense, is a reusable directory centered on a SKILL.md file that gives a compatible AI agent task-specific instructions and may bundle scripts, references, and assets.
Quick Facts
| Full Name | AI Agent Skill |
|---|---|
| Created | Concept evolved with AI agents, formalized around 2023-2024 |
| Specification | Official Specification |
How It Works
Treat the Directory as a Versioned Package
The [Agent Skills specification](https://agentskills.io/specification) requires a directory with SKILL.md; its YAML Frontmatter declares at least name and description, while the Markdown body contains instructions. Optional scripts/, references/, and assets/ hold executable helpers and supporting material. Compatible runtimes expose compact metadata during discovery, load the full instructions only after activation, and read resources on demand. Experimental allowed-tools metadata cannot replace runtime authorization.
Separate Format, Transport, and Execution
A Prompt is interaction input, ambient project guidance applies within a configured scope, a Tool exposes an executable operation, and a Plugin is a product distribution unit. Agent Skills defines a file package. The official [MCP Skills extension](https://modelcontextprotocol.io/extensions/skills/overview) can discover and transport those files, but reading a Resource does not activate the Skill or authorize its scripts and Tools. The Host still owns context assembly, origin identity, approval, credentials, side effects, cancellation, and recovery.
Verify Supply Chain and Behavior Before Promotion
Pin the source and version, enumerate every file, verify size and digest, review instructions and dependencies, declare compatibility, and reject unreviewed additions, path escapes, hidden binaries, secret collection, or unexpected network access. Run third-party scripts in a constrained Sandbox with scoped credentials and egress. Current [enterprise Skill guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise) also separates Trigger Accuracy, Isolation, Coexistence, Instruction Following, and Output Quality. Test positive, negative, ambiguous, and adversarial routing cases independently from task success and prohibited effects.
Key Characteristics
- File-based package — a directory contains required SKILL.md metadata and instructions plus optional scripts, references, and assets
- Progressive disclosure — runtimes can expose metadata first, load full instructions on activation, and fetch resources only when needed
- Workflow layer — a Skill encodes procedures, decision points, constraints, and output requirements rather than providing protocol connectivity
- Runtime-dependent behavior — invocation, tool names, optional fields, permissions, context budgets, and sandbox semantics can differ by client
- Evaluable routing — positive and negative Trigger cases must be measured separately from execution quality and task acceptance
- Supply-chain artifact — source, license, hash, dependencies, permissions, network access, review, and rollback require lifecycle governance
Common Use Cases
- Repository workflows — package local architecture rules, review criteria, test commands, and deliverable formats for a specific codebase
- Document operations — combine instructions, deterministic scripts, templates, and format-specific references for repeatable file work
- Operational runbooks — guide diagnosis and remediation while leaving live access and authorization to approved tools and systems
- Domain review — encode legal, security, data-quality, or content checklists with evidence requirements and escalation boundaries
- Tool orchestration — teach an Agent when and how to sequence built-in or MCP Tools without embedding credentials or authorization in instructions
Example
Loading code...Frequently Asked Questions
How is an Agent Skill different from a prompt or AGENTS.md?
A prompt supplies instructions in one interaction, while ambient files such as AGENTS.md provide guidance throughout a configured project scope. An Agent Skill is a discoverable package for a recognizable workflow: the runtime first sees its metadata and loads its full instructions only when selected. Product-specific scope and precedence rules still determine how these instruction sources interact.
Is an Agent Skill the same as a Tool or MCP Server?
No. A Tool exposes an executable operation, and an MCP Server exposes protocol capabilities and live data to a Host. A Skill packages reusable instructions, decision points, references, templates, and optional scripts. It can teach an Agent how to use Tools, including MCP Tools, but MCP is not the Skill file format and a Skill does not grant authorization.
Are Agent Skills portable across every AI agent?
The core folder and SKILL.md format is portable only to clients that implement the Agent Skills specification. Behavior can still differ because clients use different discovery paths, invocation rules, optional metadata, tool names, models, context budgets, sandboxes, and permission systems. Test a declared compatibility matrix instead of assuming equivalent execution.
How should a third-party Agent Skill be installed safely?
Treat it like an untrusted software dependency. Verify the source and license, pin a commit or package version and hash, inspect every instruction, script, asset, dependency, and network destination, then run it with least privilege and scoped credentials in a sandbox. Require approval for consequential effects, retain logs, and keep a tested disable or rollback path.
How should an Agent Skill be tested and versioned?
Test direct, indirect, incomplete, negative, and adversarial requests to measure Trigger Precision and Recall, then evaluate task acceptance, prohibited actions, tool use, permission handling, recovery, token use, latency, and cost. Bind the result to the exact source, artifact hash, specification snapshot, runtime, model, dependencies, policy, and evaluation-suite revision.