Agent Skills
Agent Skills are reusable capability packages for AI agents. A skill is usually a folder with a `SKILL.md` file, metadata, task instructions, and optional scripts, references, templates, or assets that the agent loads when the user asks for a matching workflow.
Skills turn repeated agent work from copy-pasted prompts into reusable, inspectable, and version-controlled capability bundles. They matter for coding agents because they can carry workflow rules, commands, project procedures, quality gates, and examples across Claude Code, GitHub Copilot, Codex, Cursor, Gemini CLI, and other compatible hosts.
Anthropic documents Agent Skills as modular capabilities that package instructions, metadata, and optional resources for Claude, with progressive loading and security caveats. The agentskills specification frames skills as an open format based on `SKILL.md`. Microsoft documents Agent Skills as an open standard for Copilot in VS Code, and GitHub documents `gh skill` commands for installation, version pinning, provenance, and supply-chain controls. Hacker News discussion shows demand around practical skills, how people misuse them, and how they differ from prompts, tools, and MCP servers.
- Use skills for reusable agent workflows, not one-off reminders.
- Prefer a `SKILL.md` plus scripts or references when the workflow needs repeatability.
- Keep prompts, tools, MCP servers, and skills conceptually separate when comparing agent systems.
- Audit third-party skills before loading them into sensitive workspaces.
An Agent Skill is a directory containing a `SKILL.md` file with metadata and instructions, plus optional supporting files. The Agent Skills open format lets authors bundle scripts for deterministic work, references for domain facts, examples for style, or templates for repeatable output. A compatible agent host discovers and loads the package; the package is not a standalone model or agent runtime.
- Agent Skills format overview
The format documentation describes the required metadata, instructions and optional resources.
- Agent Harness: the system that hosts the workflow
See where skill loading fits beside runtime state, tools, permissions and feedback.
- Discovery metadata tells the agent when the skill may be relevant.
- The main instructions explain the workflow or domain behavior.
- Optional scripts and resources let the agent use repeatable code or reference material without pasting everything into the prompt.
Agent Skills teach reusable workflows; prompts give instructions in a conversation, and tools expose callable operations. A skill can tell an agent how to use a tool or script, but the compatible host supplies execution and permissions. Skills therefore complement an agent harness rather than replacing it. For example, a testing skill can describe the procedure while the harness runs commands and records the results.
- Claude Code: a concrete agent host
Explore a product that combines instructions, tools and runtime controls.
- Agent Harness vs Agent Framework
Keep reusable instructions, developer libraries and the execution system distinct.
Agent Skills use progressive disclosure so a compatible host can load the name and description first, the full `SKILL.md` instructions when a task matches, and supporting resources during execution. This reduces the instructions needed in the initial context. It does not guarantee that every host discovers the same skill or executes the workflow correctly.
An Agent Skill can influence the commands an agent chooses and the files or external content it reads. Review third-party skill instructions and bundled scripts, check their origin, and pin versions when possible. A skill description is not a security boundary; the agent host must enforce the permissions under which code and tools run.
- Agent Skill Security: review the package and permissions
Check provenance, executable resources and access boundaries before adopting a third-party workflow.
- Agent Traces: inspect what the workflow actually did
Use recorded tool calls and results as execution evidence rather than assuming a loaded skill succeeded.
Claude Code is one of the agent hosts where custom skills are used for coding workflows.
A concrete web-agent tool that can be discussed alongside skills, MCP, and browser-control harnesses.
Local MCP connector that shows how project instructions, skills, files, shell access, and worktrees combine in a harness.
Coding harness example where skills are part of the user-facing workflow surface.
The runtime and control layer that discovers, scopes, and executes skills.
The review surface for skill provenance, scripts, permissions, and hidden instructions.
Trace evidence helps verify whether a skill changed an agent run as intended.
Skills package repeatable loops so agents do not recreate the same process from scratch.
Source confidence
Anthropic
Anthropic Engineering
Agent Skills
Agent Skills
Microsoft Docs
GitHub Changelog
Anson Biggs
Agent Skills FAQ
Practical answers about Agent Skills, how it works, and when it matters.
Are Agent Skills just prompts?+
No. A prompt is usually a single instruction in a conversation. An Agent Skill is a reusable package with metadata, task instructions, and optional scripts, references, examples, or templates that an agent can load only when a matching task appears.
How are Agent Skills different from MCP tools?+
Agent Skills teach an agent how to perform a workflow. MCP tools expose callable capabilities or external systems. A skill may tell an agent when and how to use an MCP tool, but the skill itself is not the tool server.
Why do Agent Skills need security review?+
Skills can influence planning, tool choice, file access, scripts, and external-source handling. Unknown skills can hide unsafe instructions or commands, so teams should inspect bundled files, pin trusted versions, and avoid loading unreviewed skills into sensitive projects.
When should I create an Agent Skill?+
Create a skill when a workflow is repeated, teachable, and benefits from reusable instructions, scripts, references, or templates. Do not create a skill for a one-off note or a vague preference that belongs in normal project documentation.