What Are Agent Skills? Anthropic’s Portable Skill Standard for Claude and Beyond

What Are Agent Skills?

Agent Skills are Anthropic’s open standard for packaging instructions, scripts, and supporting resources into a folder that an AI agent can discover and load on demand. Introduced publicly in late 2025 and adopted across Claude.ai, Claude Code, the Claude Agent SDK, and the Claude Developer Platform, skills are the canonical way to teach Claude a new specialty without retraining the model.

Conceptually, think of a skill the way you would think of a PowerShell module or a VS Code extension — but scoped to an AI agent. A skill is a folder containing a SKILL.md manifest (when to use it and how to use it), optional executable scripts, and any reference materials such as templates or data files. Claude scans the description field of installed skills at session start, then loads the full contents only when a user request matches.

In January 2026, skills gained live-reload: adding or editing a skill in ~/.claude/skills or .claude/skills activates immediately without a session restart. Keep in mind that this turns skills into a true iteration surface — you can author, test, and refine them as fast as you can write Markdown.

Architecturally, skills occupy the same layer of the stack as a browser extension or an IDE plugin — they extend the agent without modifying the core. That analogy is useful because it sets correct expectations. You should not expect a skill to replace the underlying model, change its safety behavior, or bypass rate limits. What a skill can do is condition how the model approaches a task: which template to use, which tools to call, which checks to run before declaring completion. Skills are fundamentally a composition and reuse primitive, not a capability primitive. Important to note: this also means that quality improvements to the base Claude model automatically improve every skill that relies on it, which is one reason teams invest in skill authoring as durable infrastructure rather than throwaway tooling.

How to Pronounce Agent Skills

In Anthropic’s documentation the term appears both as “Agent Skills” (the feature) and “skill” (a single unit), and both are acceptable. It is important to note that most people drop “agent” casually and just say “skill” in conversation once the context is established.

How Agent Skills Work

An Agent Skill has three structural pieces. First, the manifest (SKILL.md). Second, optional scripts in any language Claude can execute — Python, Node, shell, and so on. Third, optional reference resources like templates, fixtures, or images. At session start Claude reads only the YAML frontmatter from each manifest, collecting the description into a lightweight index. When a user request plausibly matches a description, Claude loads the rest of the manifest and any scripts the skill points to.

Directory Layout

The SKILL.md Manifest

A manifest is Markdown with a YAML frontmatter block. Required fields are name and description; the body contains step-by-step instructions, references to scripts in the folder, preconditions, and examples. A great description reads like a targeting rule — “use this skill whenever the user asks for X, Y, or Z” — because that’s literally what the model uses to pick skills.

Discovery vs Loading

The model never reads all skill bodies upfront. It only reads every description, which typically totals a few hundred tokens even with many skills installed. Important: when a skill activates, its body and referenced scripts are pulled in. You should budget accordingly — a 2000-token skill body is fine, but a 20000-token skill will dominate a session once it triggers.

Skill Resolution Order

When multiple skills could match a request, Claude applies a deterministic resolution order. Project-local skills in .claude/skills/ take precedence over user-level skills in ~/.claude/skills/, which in turn take precedence over system-provided reference skills. Within the same scope, Claude ranks skills by how specifically the description matches the user’s phrasing. This layering is deliberate: project owners can override a user default, and organizations can pre-install org-wide skills that every repo inherits unless explicitly shadowed. Keep in mind that when two skills match equally well, Claude will usually consult the user before proceeding — ambiguous triggering is surfaced rather than silently resolved.

Executable vs Informational Skills

Not every skill needs to run code. Many of the most useful skills are pure Markdown — a checklist, a prompt template, a writing style guide — with no scripts at all. These “informational” skills change how Claude thinks about a task rather than giving it new tools to call. Executable skills, on the other hand, bundle Python or shell scripts that the Agent SDK’s sandboxed bash tool can invoke. You should pick the right flavor for the job: informational skills are easier to write and audit, while executable skills unlock capabilities that pure instruction cannot replicate.

Agent Skills Usage and Examples

Creating a skill is as simple as making a folder and writing a SKILL.md. Put it in ~/.claude/skills/ for user-level scope or .claude/skills/ in a project for repo-level scope. Claude Code, Claude Desktop, and the Agent SDK all pick skills up from both paths.

A Minimal Skill

# ~/.claude/skills/weekly-report/SKILL.md
---
name: weekly-report
description: Produce a Markdown weekly status report. Trigger whenever the user asks for "this week's report," "weekly report," or similar.
---

# Weekly Report Skill

## Steps
1. Read this week's work logs from `~/documents/weekly-logs/`
2. Generate a Markdown document using the template below
3. Save to `weekly-report-YYYY-MM-DD.md`

## Template
```markdown
# Weekly Report (YYYY, Week N)

## Wins
- [Bulleted accomplishments]

## Issues / Blockers
- [Bulleted blockers]

## Next Week
- [Bulleted plan]
```

Skills With Scripts

When instructions alone aren’t enough — you need real computation — drop scripts into the skill folder and reference them from the manifest. The SDK’s sandboxed bash tool runs them with the same permission scope as the rest of the session. Teams routinely ship skills that call internal APIs, parse proprietary file formats, or wrap command-line tooling.

Official Pre-Built Skills

Anthropic maintains a public repository at github.com/anthropics/skills containing reference skills for common document work: pptx (PowerPoint), xlsx (Excel), docx (Word), and pdf. These are battle-tested and intentionally written as exemplars — cloning and adapting them is the fastest way to learn idiomatic skill authoring.

Reading the official skills is itself an educational exercise. The docx skill, for example, demonstrates how to structure a multi-stage workflow that parses an input document, applies transformations, and writes a valid output — all while handling edge cases like embedded images, tracked changes, and unusual styles. The pptx skill shows how to combine a template library with Claude’s layout reasoning to produce presentations that look like a human designer built them. Anthropic deliberately wrote these reference skills to be readable top-to-bottom rather than compressed, so you should take the time to walk through at least one before authoring a production skill of your own.

Skill Patterns That Work Well

Experienced authors converge on a few repeatable patterns. The “wizard” pattern walks Claude through a multi-step procedure with explicit numbered stages, useful for workflows that must not skip checks. The “template” pattern bundles a canonical output format (a report layout, an email style, a slide master) and instructs Claude to fill it in. The “checker” pattern has Claude validate an existing artifact against rules and emit a diff. The “extractor” pattern turns unstructured input (chat logs, PDFs) into structured data according to a schema. Important to note: a single skill should usually pick one pattern and stay narrow — a kitchen-sink skill that tries to do everything rarely triggers cleanly.

Testing and Iteration

A skill is easier to iterate on than you might expect. Edit the SKILL.md, invoke Claude with a phrase that should match, and watch whether it picks up the skill; if not, adjust the description until it does. For executable skills, keep scripts small and pure where possible so that a change to the manifest does not require rerunning a long script. Enterprise teams have begun to adopt CI pipelines that lint skills for schema correctness and run “trigger tests” — synthetic user messages paired with expected skill activations — to catch regressions before publishing.

Advantages and Disadvantages of Agent Skills

Advantages

Dynamic loading is the headline win — a hundred installed skills cost only a few thousand tokens of index pressure, not a hundred full-skill contexts. Because skills are just folders, they version-control cleanly in Git, distribute as zips, and travel with a project. Institutional knowledge that used to live in a wiki no one reads can be reshaped into skills that Claude actively uses. You should also note that admins can deploy skills organization-wide with automatic updates on Enterprise plans.

Disadvantages

The skill feature shipped first inside the Claude ecosystem, so portability to non-Claude agents is still early — the spec is open but adoption is uneven. Skill discovery is only as good as the description you write; vague descriptions either fail to trigger or trigger inappropriately. Important: you should treat description authoring as a first-class UX concern, not a throwaway comment.

There is also an observability gap. Because skills activate implicitly based on description matching, debugging why a skill did not fire can be frustrating — you are essentially reverse-engineering the model’s ranking. The Agent SDK exposes some introspection hooks (you can ask Claude “which skills did you consider and why?”) but these are qualitative rather than quantitative. Until tooling matures, teams building mission-critical workflows should prefer explicit invocations or narrow, keyword-rich descriptions over fuzzy natural-language triggers.

Agent Skills vs MCP vs Tools

Agent Skills are often confused with MCP servers or the Tools API. They solve different problems.

The short way to remember the split: skills teach Claude how, MCP servers give Claude access, and tools expose primitives. Production agents mix and match all three.

A concrete example clarifies the layering. Suppose you want Claude to generate a monthly sales report. The MCP layer connects Claude to Salesforce and Google Sheets. The Tools layer lets Claude read ranges and send messages. The Skill layer — “monthly-sales-report” — tells Claude which queries to run, which sheet to write to, which tone to adopt, and how to escalate if numbers look anomalous. Without the skill, Claude has access and primitives but no procedure; without the tools, a skill has instructions but no way to act; without MCP, the tools have no services to reach. All three layers need to be designed together for a robust agentic workflow.

Common Misconceptions

Misconception 1: Skills Are Claude-Only

Anthropic published Agent Skills as an open standard in December 2025 with the explicit aim of cross-platform portability. Other vendors and open-source projects are already experimenting with compatible loaders. Note that while the format is open, the highest-fidelity implementation today still lives inside Claude products.

Misconception 2: Every Installed Skill Costs Context

No — the loader only ingests descriptions at session start. Full skill bodies are loaded lazily, so an inventory of a hundred skills costs a few thousand tokens of index pressure, not a hundred full contexts. Keep in mind that individual skill activations do add load; budget on a per-trigger basis.

Misconception 3: Skills Are Only for Claude Code

Claude Code shipped first, but Claude.ai, the Agent SDK, and the Developer Platform all support skills now. One of the explicit goals of the open spec is identical behavior across surfaces.

Misconception 4: A Skill Is Like a Prompt Preset

Prompt presets are pinned text that the user toggles explicitly. A skill is fundamentally different: Claude selects it based on context, not user toggling. The preset is the equivalent of setting a reminder; the skill is the equivalent of having an expert on call who shows up when you need them. Important to note: both have valid uses, but conflating them leads to authoring skills as if they were presets, which tends to produce passive or inert skills that do not trigger when they should.

Misconception 5: Skills Must Be Short to Load Fast

Length of a skill body has minimal impact on session start time because only the description is indexed at boot. Once a skill activates, its body is loaded, but that cost is part of solving the user’s problem — not overhead. You should write the body as long as it needs to be to be clear and unambiguous. Terse skills force Claude to infer missing steps, which is exactly what skills exist to avoid.

Real-World Use Cases

Teams codify internal playbooks — contract review procedures, incident-response runbooks, coding standards — into skills that ship via Git. When a new hire opens Claude Desktop with the org’s skills already installed, they inherit hundreds of procedures on day one. Platform teams publish “golden-path” skills for common tasks so engineers stop reinventing them in every repo.

Representative Examples

1. CI/CD triage: a skill that walks Claude through diagnosing a red build.
2. Contract review: a skill encoding your company’s NDA checklist.
3. Budget modeling: a skill that enforces a templated financial model.
4. PR review: a skill encoding your engineering standards.
5. Support escalation: a skill with decision trees and templated responses.

Industry-Specific Applications

In financial services, teams ship risk-assessment skills that encode regulatory checklists (KYC, AML, Basel III requirements) directly into Claude’s workflow so every analysis covers the same compliance bases. Healthcare organizations package clinical decision-support skills that encode evidence-based guidelines — Claude cites the guideline version and specific clause every time it applies one. In software development, platform teams publish code-scaffold skills that produce boilerplate consistent with internal frameworks, so a microservice generated by any engineer has the same observability, logging, and deployment wiring. In marketing, brand-voice skills enforce tone and banned-word lists across every piece of copy Claude drafts.

Why Skills Beat Wiki Pages

Before skills, institutional knowledge tended to live in wikis that new hires were told to “read first.” In practice, those wikis were rarely consulted. Skills invert the pattern: the knowledge is consulted every time a matching task comes up, without the human having to remember to look. Important to note: this changes the economics of writing procedure documentation. A wiki page that no one reads is dead weight; the same content reshaped into a skill is called dozens of times a day. Teams that have made this transition report that previously “undocumented” tribal knowledge actually turns out to be well-documented — just not in a form anyone used to consume.

Frequently Asked Questions (FAQ)

Q. How do skills differ from Claude Code slash commands?

A. Slash commands are explicit user-invoked shortcuts. Skills trigger based on matching the description against the conversation. You can mix them — a command can invoke a skill.

Q. Where can I share skills?

A. The official anthropics/skills repository, third-party registries, and private internal registries are all options. Enterprise plans include centralized distribution for org-wide skills.

Q. Are skills safe to install?

A. Scripts inside a skill run in the Agent SDK sandbox with the same permission scope as the rest of the session. That said, you should review third-party skills exactly as you would review any code before running it. Treat skill authors as code contributors.

Q. Can Cursor or Cline consume skills?

A. As of April 2026 the spec’s primary consumers are Claude products, but because the format is open, other agents are beginning to add skill-compatible loaders.

Q. How large can a skill be?

A. There is no hard cap, but practical guidance is to keep a single skill body under roughly 5000 tokens of Markdown and offload heavier reference material to files that the skill instructs Claude to read on demand. You should remember that larger skills consume more context once they activate — split a sprawling skill into multiple focused skills if it exceeds that budget.

Q. Can one skill invoke another skill?

A. Skills do not invoke each other directly. Instead, a skill can instruct Claude to consult another skill by name, which Claude then loads conditionally. This keeps the dependency relationship declarative and avoids hidden coupling.

Q. How do I version skills?

A. Because skills are folders, standard Git versioning applies — tag releases, branch for experiments, merge via pull request. Teams typically publish a CHANGELOG.md inside each skill and include a version field in the frontmatter.

Q. What happens if a skill description is ambiguous?

A. Claude will usually ask for clarification rather than silently pick one. Still, you should author descriptions that begin with a clear trigger pattern (e.g., “use this skill when the user asks to …”) to minimize ambiguity. Keep in mind that description quality is the single largest factor in whether a skill behaves predictably.

Conclusion

Agent Skills are the specification that turns Claude from a general-purpose assistant into a domain specialist tailored to your organization. By packaging instructions, templates, and executable scripts into a simple folder plus manifest, skills make institutional knowledge portable, version-controlled, and automatically consulted. The open specification means the same skills can evolve across platforms as other vendors adopt the format, protecting your authoring investment regardless of which agent you deploy.

For individual developers, skills are the easiest way to make Claude consistently helpful on recurring tasks — you write the procedure once and stop re-prompting. For teams, skills are a mechanism to externalize tribal knowledge into a form Claude actually uses. For enterprises, skills are the foundation of a governance strategy that distinguishes approved workflows from improvised ones. Keep in mind that adoption tends to follow a predictable curve: engineers start with tiny personal skills, grow a team library, and eventually converge on an organization-wide registry that every new deployment inherits from day one.

• Agent Skills are Anthropic’s open, folder-based skill format for AI agents.
• A SKILL.md manifest plus optional scripts and resources is all that’s required.
• Dynamic loading keeps context pressure low even with many skills installed.
• Works across Claude.ai, Claude Code, the Agent SDK, and Developer Platform.
• Official pre-built skills for pptx / xlsx / docx / pdf are free to use and modify.
• Skills ≠ MCP servers ≠ tools — they fill complementary roles.
• The open standard is gaining cross-platform traction.

References