The Agent Skills Guide

Remember the scene in The Matrix where Neo gets Kung Fu uploaded directly into his brain? "I know Kung Fu." Agent Skills work the same way — except for AI agents. You upload a skill file, and suddenly your agent knows about SEO, how to write cold emails, or even accounting in France.

This reference covers what skills are, how they work under the hood, the open specification, how to create your own, best practices, and which platforms support them.

What is an Agent Skill?

An Agent Skill is a folder containing a SKILL.md file — a Markdown document with metadata and instructions that teaches an AI agent how to perform a specific task. Skills can also include scripts, templates, reference documents, and other resources.

Think of it like an onboarding guide you'd write for a new team member. It contains the procedural knowledge, domain context, and workflows needed to do a specific job well. The agent reads it when relevant and follows the instructions.

At its simplest, a skill is just this:

my-skill/
└── SKILL.md

And the SKILL.md file looks like this:

---
name: code-review
description: Reviews code for bugs, security issues, and style violations. Use when the user asks for a code review or submits a pull request.
---

# Code Review

## When to use this skill
Use when the user asks for a code review, submits code for feedback, or opens a pull request.

## Process
1. Read the code carefully
2. Check for bugs and edge cases
3. Look for security vulnerabilities
4. Verify style consistency
5. Provide actionable feedback with examples

That's it. No SDK, no API integration, no deployment pipeline. A skill is a file.

Why Agent Skills Matter

AI agents are increasingly capable, but they lack two critical things: your context and your procedures. Skills solve both problems.

The Problem

Without skills, every conversation starts from zero. You have to explain your team's coding conventions, your company's review process, your preferred tools, and your domain-specific knowledge — every single time.

What Skills Enable

Domain expertise. Package specialized knowledge into reusable instructions — legal review processes, data analysis pipelines, financial modeling workflows.

New capabilities. Give agents abilities they don't have out of the box — creating PowerPoint presentations, processing PDFs, building MCP servers, analyzing datasets with your company's specific schemas.

Repeatable workflows. Turn multi-step tasks into consistent, auditable processes. A skill for database migrations always follows the same validation steps.

Interoperability. Write a skill once, use it across Claude, Cursor, Codex, and 25+ other compatible platforms. The same SKILL.md file works everywhere.

Team knowledge sharing. Capture institutional knowledge in version-controlled packages. When someone leaves the team, their expertise stays in the skills they wrote.

For Different Audiences

• For skill authors: Build capabilities once and deploy them across multiple agent products.
• For compatible agents: Supporting skills lets end users extend agent capabilities out of the box.
• For teams and enterprises: Capture organizational knowledge in portable, version-controlled packages.

How Skills Work: Progressive Disclosure

The key architecture behind skills is progressive disclosure — loading information in stages to keep context efficient.

Three Levels of Loading

Level 1: Metadata (~100 tokens per skill)

At startup, the agent loads only the name and description from every available skill. This is injected into the system prompt so the agent knows what skills exist and when they might be relevant.

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files.
---

This means you can install dozens of skills with almost no context cost. The agent just keeps a lightweight index.

Level 2: Instructions (< 5,000 tokens recommended)

When a user's request matches a skill's description, the agent reads the full SKILL.md body into context. This is where the real instructions live — workflows, best practices, code examples, and decision trees.

# PDF Processing

## Quick start
Use pdfplumber for text extraction:

    import pdfplumber
    with pdfplumber.open("document.pdf") as pdf:
        text = pdf.pages[0].extract_text()

## Form filling
See [FORMS.md](FORMS.md) for the complete form-filling guide.

Level 3: Resources (loaded as needed)

Skills can bundle additional files — reference documents, scripts, templates, schemas. These are loaded only when the instructions reference them. A skill can include comprehensive API documentation, large datasets, or extensive examples without any context penalty until they're actually needed.

pdf-skill/
├── SKILL.md            # Main instructions
├── FORMS.md            # Form-filling guide (loaded if needed)
├── REFERENCE.md        # API reference (loaded if needed)
└── scripts/
    ├── extract.py      # Executed, not loaded into context
    └── validate.py     # Only output enters context

Why This Architecture Works

The filesystem-based model means scripts are executed without loading their source code into context. Only the script's output consumes tokens. This makes scripts far more efficient than having the agent generate equivalent code.

The SKILL.md Specification

Every skill starts with a SKILL.md file containing YAML frontmatter and Markdown content.

Required Fields

Optional Fields

Complete Example

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
license: Apache-2.0
compatibility: Requires pdfplumber, pypdf. Works with Claude Code or similar.
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(python:*) Read
---

Name Validation Rules

Valid:

• pdf-processing
• data-analysis
• code-review

Invalid:

• PDF-Processing — uppercase not allowed
• -pdf — cannot start with hyphen
• pdf--processing — consecutive hyphens not allowed
• my_skill — underscores not allowed

Writing Effective Descriptions

The description is the most critical field. It's what the agent uses to decide whether to activate the skill. A good description includes both what the skill does and when to use it.

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad:

description: Helps with PDFs.

Always write in third person. The description is injected into the system prompt, and inconsistent point-of-view causes discovery problems.

• Good: "Processes Excel files and generates reports"
• Bad: "I can help you process Excel files"

Skill Directory Structure

A minimal skill needs just one file. A complete skill can include several directories:

my-skill/
├── SKILL.md              # Required: instructions + metadata
├── scripts/              # Optional: executable code
│   ├── extract.py
│   └── validate.py
├── references/           # Optional: documentation
│   ├── REFERENCE.md
│   └── API.md
└── assets/               # Optional: templates, resources
    ├── template.docx
    └── schema.json

scripts/

Executable code that agents run. Scripts should be self-contained, include helpful error messages, and handle edge cases. Supported languages depend on the agent (Python, Bash, and JavaScript are common).

Scripts provide deterministic operations without consuming context. When the agent runs validate.py, the script's source code never enters the context window — only the output does.

references/

Additional documentation the agent reads on demand. Keep individual files focused — smaller files mean less context usage when loaded.

assets/

Static resources: document templates, image examples, lookup tables, JSON schemas.

File References

When referencing other files in your skill, use relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script: `python scripts/extract.py`

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains — the agent may only partially read files that are referenced from other referenced files.

Supported Platforms

Agent Skills are an open standard supported by 25+ AI development tools. The same SKILL.md file works across all of them.

Major Platforms

Full List of Compatible Platforms

Claude Code, Claude.ai, Cursor, OpenAI Codex, VS Code, GitHub Copilot, Windsurf, Gemini CLI, Amp, Roo Code, Goose, Cline, OpenCode, TRAE, Firebender, Piebald, Factory, Databricks, Spring AI, Letta, Agentman, Autohand, Mux, Command Code, Qodo, Ona, VT Code, Mistral Vibe, and more.

How to Create a Skill

Step 1: Create the Directory

mkdir my-skill
cd my-skill

Step 2: Write SKILL.md

Create a SKILL.md file with frontmatter and instructions:

---
name: my-skill
description: Does X when the user asks for Y. Handles A, B, and C scenarios.
---

# My Skill

## When to use
Use this skill when the user needs to...

## Process
1. First, do this
2. Then, check that
3. Finally, output the result

## Examples

### Input
"Can you review this pull request?"

### Output
A structured review with sections for bugs, security, style, and suggestions.

Step 3: Add Supporting Files (Optional)

mkdir scripts references assets

Add scripts for deterministic operations, reference docs for detailed context, and assets for templates.

Step 4: Install the Skill

Claude Code:

# Project-level (shared with team)
cp -r my-skill .claude/skills/

# User-level (personal)
cp -r my-skill ~/.claude/skills/

Cursor:

cp -r my-skill .cursor/skills/

OpenAI Codex:

cp -r my-skill .agents/skills/

Step 5: Test and Iterate

Use the skill in real tasks. Watch how the agent uses it. Refine based on what works and what doesn't.

Validation

Use the official reference library to validate your skill:

skills-ref validate ./my-skill

This checks frontmatter validity and naming conventions.

Best Practices

These guidelines come directly from Anthropic's official documentation and real-world experience.

Be Concise

The context window is shared between your skill, the system prompt, conversation history, and other skills. Only include what the agent doesn't already know.

Good (~50 tokens):

## Extract PDF text
Use pdfplumber for text extraction:

    import pdfplumber
    with pdfplumber.open("file.pdf") as pdf:
        text = pdf.pages[0].extract_text()

Bad (~150 tokens):

## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use...

The agent already knows what PDFs are. Skip the preamble.

Set Appropriate Degrees of Freedom

Match instruction specificity to the task's fragility:

High freedom — multiple approaches are valid:

## Code review
1. Analyze code structure
2. Check for bugs and edge cases
3. Suggest readability improvements
4. Verify project conventions

Low freedom — consistency is critical:

## Database migration
Run exactly this script:
    python scripts/migrate.py --verify --backup
Do not modify the command or add flags.

Use Progressive Disclosure

Keep SKILL.md under 500 lines. Move detailed reference material to separate files that the agent loads on demand.

# Main Skill

## Quick start
[Core instructions here]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

Include Feedback Loops

For quality-critical tasks, build validation into the workflow:

## Document editing
1. Make edits to the XML
2. Validate: `python scripts/validate.py`
3. If validation fails, fix issues and validate again
4. Only proceed when validation passes
5. Rebuild: `python scripts/pack.py output.docx`

Provide Utility Scripts

Pre-built scripts are more reliable than generated code, save tokens, and ensure consistency:

## Utility scripts

**analyze_form.py**: Extract form fields from PDF
    python scripts/analyze_form.py input.pdf > fields.json

**validate.py**: Check for overlapping fields
    python scripts/validate.py fields.json

Write Workflow Checklists

For complex multi-step tasks, provide a checklist the agent can track:

## Deployment workflow

Task Progress:
- [ ] Step 1: Run tests
- [ ] Step 2: Build production assets
- [ ] Step 3: Validate configuration
- [ ] Step 4: Deploy to staging
- [ ] Step 5: Run smoke tests
- [ ] Step 6: Deploy to production

Use Consistent Terminology

Pick one term and stick with it:

• Always "API endpoint" (not "URL", "API route", "path")
• Always "field" (not "box", "element", "control")
• Always "extract" (not "pull", "get", "retrieve")

Naming Conventions

Use gerund form (verb + -ing) for skill names:

• processing-pdfs
• analyzing-spreadsheets
• testing-code
• writing-documentation

Avoid vague names like helper, utils, or tools.

Test Across Models

What works for Claude Opus might need more detail for Haiku. Test with all models you plan to use:

• Haiku: Does the skill provide enough guidance?
• Sonnet: Is the skill clear and efficient?
• Opus: Does the skill avoid over-explaining?

Pre-Built Skills from Anthropic

Anthropic provides pre-built skills for common document tasks:

These are available on Claude.ai (automatic) and via the Claude API (using skill_id).

Partner Skills

Professionally-built integrations from Notion, Figma, Atlassian, and others, designed to work with their MCP connectors.

Organization Skills

For Team and Enterprise users, administrators can distribute approved skills organization-wide with default enable/disable settings.

Using Skills via the Claude API

Skills in the API require three beta headers and the code execution tool:

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "files-api-2025-04-14"
    ],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",
                "version": "latest"
            }
        ]
    },
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }],
    messages=[{
        "role": "user",
        "content": "Create a monthly budget spreadsheet with income, expenses, and a chart"
    }]
)

Listing Available Skills

skills = client.beta.skills.list(
    source="anthropic",
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title}")

Uploading Custom Skills

Custom skills can be uploaded via the /v1/skills endpoints and are shared organization-wide.

Downloading Generated Files

for block in response.content:
    if hasattr(block, 'file_id'):
        file_data = client.beta.files.content.retrieve(block.file_id)
        with open("output.xlsx", "wb") as f:
            f.write(file_data.content)

Using Skills in Claude Code

Claude Code supports filesystem-based custom skills. No API upload needed.

Skill Locations

.claude/skills/       # Project-level (shared via git)
~/.claude/skills/     # User-level (personal)

Creating a Skill

mkdir -p .claude/skills/my-skill

Then create .claude/skills/my-skill/SKILL.md with your instructions.

Invoking Skills

Skills activate automatically when your request matches the skill's description. You can also invoke them explicitly as slash commands by typing /skill-name in the chat.

Sharing Skills

Project-level skills (in .claude/skills/) are committed to git and shared with your team automatically. User-level skills (in ~/.claude/skills/) stay personal.

Skills can also be shared via Claude Code Plugins.

Using Skills in Cursor

Cursor 2.4+ supports Agent Skills with automatic detection and manual invocation.

Skill Locations

Cursor scans these directories:

• .cursor/skills/ — project-level
• ~/.cursor/skills/ — user-level
• .claude/skills/ and .codex/skills/ — cross-platform compatibility

Invoking Skills

• Automatic: Cursor determines when to apply relevant skills based on context
• Manual: Type / followed by the skill name in Agent chat

Special Fields

Cursor supports a disable-model-invocation field in frontmatter. When set to true, the skill becomes a slash command only — it won't activate automatically.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Migration

Cursor 2.4 includes /migrate-to-skills to convert existing dynamic rules and slash commands into the skills format.

Using Skills in OpenAI Codex

Codex scans multiple hierarchical locations for skills:

Skill Locations

1. $CWD/.agents/skills — current directory
2. $REPO_ROOT/.agents/skills — repository root
3. $HOME/.agents/skills — user-level
4. /etc/codex/skills — system/admin level

Activation

• Explicit: Users invoke via /skills command or $ mention
• Implicit: Codex autonomously selects skills when tasks match the description

Configuration

Skills can be disabled in ~/.codex/config.toml:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Codex-Specific Features

The optional agents/openai.yaml file controls UI appearance, icons, branding, and declares MCP tool dependencies.

Skills vs MCP: What's the Difference?

Skills and MCP (Model Context Protocol) are complementary technologies, not competitors.

When to use skills: Procedural knowledge, workflows, domain expertise, best practices, templates.

When to use MCP: API integrations, database access, external tool connections, real-time data.

Together: A skill can reference MCP tools. For example, a "database analysis" skill might include instructions that reference MCP tools for querying BigQuery. Use fully qualified tool names: BigQuery:bigquery_schema.

Skills vs Agents

Skills and agents are different layers of the AI stack.

An agent is like a person. A skill is like a training manual. Multiple agents can share the same skills, and one agent can use many skills.

Example: A marketing agent might use SEO skills, content writing skills, and analytics skills. A development agent might use code review skills, testing skills, and deployment skills. Both agents might share a "writing documentation" skill.

Security Considerations

Skills provide agents with new capabilities through instructions and code. Use only skills from trusted sources.

Key Risks

• Malicious instructions: A skill can direct the agent to invoke tools or execute code in ways that don't match its stated purpose
• Data exfiltration: Skills with access to sensitive data could leak information to external systems
• Tool misuse: Skills can invoke file operations, bash commands, and code execution in harmful ways
• External dependencies: Skills that fetch data from URLs pose risk — fetched content may contain malicious instructions

Mitigation

• Audit thoroughly: Review all files — SKILL.md, scripts, images, and other resources
• Treat like software: Only install skills from trusted sources
• Sandbox execution: Run scripts in isolated environments
• Confirm dangerous operations: Ask users before running destructive commands
• Log everything: Record script executions for auditing

Platform-Specific Constraints

The Open Standard

Agent Skills were originally developed by Anthropic, released as an open standard, and adopted by a growing ecosystem of agent products.

The specification is maintained at github.com/agentskills/agentskills and is open to contributions.

Reference Library

The skills-ref Python library provides utilities for working with skills:

# Validate a skill directory
skills-ref validate ./my-skill

# Generate XML for agent prompts
skills-ref to-prompt ./my-skill

Integration for Platform Developers

If you're building an agent or development tool, adding skills support means:

1. Discover skills in configured directories
2. Parse YAML frontmatter from each SKILL.md
3. Inject skill metadata into the system prompt
4. Match user tasks to relevant skills
5. Load full instructions when a skill is activated
6. Execute scripts and access resources as needed

The recommended system prompt format for Claude models uses XML:

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
</available_skills>

FAQ