What Are Agent Skills?

Agent skills are reusable capability packages that teach an AI agent how to perform a repeatable workflow. A skill usually starts with a compact instruction file, commonly named SKILL.md, and can include supporting references, scripts, examples, templates, or assets that the agent opens only when the task calls for them.

The important shift is that a skill is not just a prompt. A prompt tells the agent what to do once. A skill gives the agent a durable way to recognize a class of tasks, load the right procedure, and apply the same operating standard across projects or sessions. That makes skills a practical building block for agentic coding, AI software engineering, and governed AI agent operations.

Most skill systems separate the short routing instructions from the heavier working context. The exact fields and directory names vary by platform, but the common shape is stable enough to design for.

SKILL.md is the entrypoint. It usually contains metadata such as a name and description, then the operating instructions the model should follow. References hold longer guidance. Scripts provide deterministic helpers. Assets and templates make outputs consistent without forcing the model to invent structure from memory.

Keep the main skill small. A large skill that loads every possible rule upfront turns into another giant prompt. A good skill points to supporting material clearly enough that the agent can pull the right file at the right time.

Agent skills work because they use progressive disclosure. The agent sees just enough information to know a skill exists, then loads the full procedure only when the current task matches it.

This matters for context windows. A team may have dozens of skills for code review, deployment, documentation, security, frontend design, or data analysis. Loading every full instruction file at startup would waste context and make the agent less focused. Loading only metadata first keeps the agent aware of available capabilities without flooding the conversation.

Skills sit between one-off instructions and executable infrastructure. The boundaries matter because teams often use the same word for different layers of the system.

• Prompts are conversation instructions. They are flexible, but usually not durable or discoverable.
• Project instruction files such as AGENTS.md or CLAUDE.md describe the repository, team conventions, and standing rules.
• Skills package repeatable know-how for a task type, often with supporting files or scripts.
• Tools and MCP servers expose executable capabilities or external systems the agent can call.
• Agents and subagents are the workers that reason, choose skills or tools, and produce artifacts.

A code-review skill might tell an agent how to inspect a diff. An MCP server might let that agent fetch pull request comments. AGENTS.md might explain the repo's review standards. The agent ties those pieces together. They are complementary, not replacements for each other.

For the deeper comparison, see the planned guide: skills vs agents vs MCP.

The SKILL.md pattern is becoming familiar across AI coding tools, but portability is not automatic. Each platform decides how skills are discovered, whether they can be invoked directly, where they live, what metadata is supported, and which commands or tools they may execute.

The safest content strategy is to explain the shared pattern first, then anchor platform-specific claims to official docs. A Claude Code page should use Claude's skill rules. A Codex page should use Codex's skill docs and discuss AGENTS.md separately. An OpenClaw page should cover its registry, precedence, and security posture without projecting those behaviors onto other tools.

Planned platform guides: Claude skills, OpenCode skills, OpenClaw skills, and Codex agent skills.

The best early skills are narrow, high-frequency workflows with a clear definition of done. They reduce repeated prompting without giving the agent vague authority over the whole repository.

Treat these pages as implementation patterns, not universal install instructions. The same skill concept may need different paths, metadata, or permission settings in different agents.

Skills change agent behavior. Some skills also execute helper scripts or route the agent toward tools with real privileges. That means skill adoption belongs in the same governance conversation as dependencies, CI scripts, prompts, and agent permissions.

The core question is simple: if a skill caused a bad change, leaked data, or invoked the wrong tool, could your team explain which skill was active, who approved it, what permissions it had, and what the agent did because of it? If the answer is no, the skill is not ready for broad use.

For the deeper risk model, see the planned guide: agent skill security.

A good skill reads less like a manifesto and more like a contract for a specific job. It should state when to use it, what inputs it expects, what steps to follow, what files or tools to inspect, what output to produce, and where the agent must stop for human review.

• Start with the trigger. The description should make routing obvious.
• Keep scope narrow. One skill should not review code, deploy production, update docs, and file compliance evidence.
• Point to references. Move long policy details and examples into separate files.
• Prefer deterministic helpers. Use scripts for parsing, validation, or repeatable checks instead of asking the model to improvise.
• Define the output. Give the agent a concrete report, diff, checklist, or artifact shape.
• Define the stop conditions. Tell the agent which actions require approval, escalation, or a human reviewer.

Skills make AI agents more useful, but they also multiply the number of behavioral rules operating inside your engineering workflow. Enterprise teams need a way to see which agents ran which skills, which tools were called, what files changed, and which human approved the outcome.