Agent Skills Cheatsheet: Packaging Know-how for AI Agents

Every team that uses an AI agent for real work ends up writing the same paragraph again and again: "Our reports use this template. Always filter out test accounts. Run the linter before you commit. Here is how our deploy works." That paragraph lives in a chat history, a wiki page, or a system prompt that keeps growing until nobody dares to edit it.

On October 16, 2025 Anthropic launched Agent Skills, a deliberately simple answer to that problem: put the know-how in a folder, with a Markdown file that says what it is for, plus whatever scripts and reference files it needs. The agent sees a one-line description of every installed skill, and opens the folder only when a task calls for it. Simon Willison's reaction the same day was that skills might be "a bigger deal than MCP", mostly because they are so simple.

Two months in, skills work across the Claude apps, Claude Code and the API, Anthropic has published a set of example and document skills, and the format is documented in a short specification. This cheatsheet collects what you need to write, ship and review them.

1. Definitions

Anthropic's engineering post puts it this way: "Building a skill for an agent is like putting together an onboarding guide for a new hire." That analogy is the best mental model: a skill is not code that the agent calls, it is documentation (and tools) that the agent reads and uses.

2. Anatomy of a skill

A minimal skill is one file:

weekly-report/
  SKILL.md

A larger one bundles more:

pdf-processing/
  SKILL.md          # overview and instructions (loaded when triggered)
  FORMS.md          # form-filling guide (loaded only if needed)
  REFERENCE.md      # detailed API reference (loaded only if needed)
  scripts/
    fill_form.py    # executed, not loaded into context
    validate.py

And the SKILL.md itself:

---
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.
---

# PDF Processing

## Quick start
Use pdfplumber to extract text. See REFERENCE.md for advanced options.

## Filling forms
Read FORMS.md and follow it exactly. Always run scripts/validate.py before saving.

Frontmatter fields

The Markdown body has no required structure. Typical sections: quick start, step-by-step workflow, rules, examples, and pointers to bundled files.

3. Progressive disclosure: why skills scale

This is the core design idea, and the reason you can install dozens of skills without filling the context window.

From the engineering post: "The metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context." The agent then reads SKILL.md with a normal file read, and opens other files the same way.

Two consequences:

• The description is the trigger. If the description is vague, the skill never loads, however good the body is.
• Bundled content is close to free until used. A skill can ship a large schema reference or a long style guide. It costs context only on the tasks that need it.

4. Scripts and resources

Skills can include code "for Claude to execute as tools at its discretion" (engineering post). This is what separates skills from a folder of prompts.

Why scripts matter:

• Reliability. Sorting a list, parsing a PDF form or validating a JSON file is better done by tested code than by tokens generated on the fly.
• Efficiency. When the agent runs a script, the code never enters the context, only its output does.
• Consistency. Every run uses the same logic, so results are comparable.

Be explicit about intent in SKILL.md: "Run scripts/validate.py" (execute) is different from "See scripts/validate.py for the algorithm" (read as reference).

5. Where skills run

Practical notes:

• Custom skills do not sync across surfaces. A skill uploaded to claude.ai is not available in the API, and Claude Code reads its own folders. Keep the source in a repository and publish it to each surface.
• On the API, skills require the code execution tool and, during the beta, beta headers (code-execution-2025-08-25, skills-2025-10-02, plus files-api-2025-04-14 if you download generated files).
• Claude Code plugins can distribute skills. Anthropic's anthropics/skills repository can be added as a plugin marketplace with /plugin marketplace add anthropics/skills.

API example (beta, as documented in Anthropic's cookbook)

import anthropic

client = anthropic.Anthropic()  # anthropic>=0.71.0

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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 a summary chart."}],
)

# Uploading a custom skill from a local folder:
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Weekly report",
    files=files_from_dir("skills/weekly-report"),
)
print(skill.id)

6. Skills vs. MCP vs. system prompts vs. subagents

These are complementary, not competing. Each solves a different problem.

Rules of thumb:

• If it is about access, use MCP (or a plain tool). A skill cannot give the agent credentials or an API it does not have.
• If it is about method, use a skill. "How to write our incident report", "how to use our internal CLI", "how to query the sales schema".
• Combine them. A skill can teach the agent how to use an MCP server well: which tools to call, in what order, with which filters. Anthropic's best practices recommend fully qualified MCP tool names in skills (ServerName:tool_name).
• Keep the system prompt short. Move anything task-specific out of it and into skills, so it loads only when relevant.
• Subagents and skills compose. A subagent can use skills inside its own context; skills do not isolate context by themselves.

7. Authoring tips

Condensed from Anthropic's "Skill authoring best practices" and the example skills:

1. Start from real failures. Run the agent on representative tasks without a skill, note what it gets wrong or keeps asking, and write only what fixes that. The docs suggest building at least three evaluation scenarios before writing extensive instructions.
2. Write the description first, in third person. "Processes Excel files and generates reports. Use when..." rather than "I can help you...". Include the words a user would actually type.
3. Be concise. Assume the model is already capable; do not explain what a PDF is. Every token in SKILL.md competes with the conversation once loaded.
4. Keep SKILL.md under about 500 lines. Split the rest into separate files and link them from SKILL.md.
5. Keep references one level deep. Link every reference file directly from SKILL.md. Chains of "see A, which says see B" lead to partial reads.
6. Match freedom to fragility. Open-ended tasks get high-level guidance. Fragile operations (migrations, form filling) get an exact script and "do not modify the command".
7. Add feedback loops. "Run the validator, fix errors, repeat until it passes" improves quality more than any wording change.
8. Scripts should solve, not punt. Handle errors in the script with clear messages, document constants, and list dependencies.
9. Name descriptively. processing-pdfs or pdf-processing, not helper or utils. Use forward slashes in paths.
10. Avoid time-sensitive instructions like "before August use the old API". Put legacy notes in a clearly marked "old patterns" section.
11. Test with every model you plan to use. What is enough for a large model may be too little for a small one.
12. Watch how the agent navigates. If it never opens a file, the file is unnecessary or badly signposted. If it opens the same file every time, that content belongs in SKILL.md.

A tiny frontmatter validator

Catch the basic errors before uploading. Standard library only, intentionally simple (it handles single-line values, which is what most skills use):

import re
import sys
from pathlib import Path

NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
RESERVED = ("anthropic", "claude")


def parse_frontmatter(text: str) -> dict[str, str]:
    if not text.startswith("---\n"):
        raise ValueError("SKILL.md must start with '---' frontmatter")
    block = text[4:].split("\n---", 1)[0]
    fields = {}
    for line in block.splitlines():
        if ":" in line and not line.startswith(" "):
            key, value = line.split(":", 1)
            fields[key.strip()] = value.strip().strip('"')
    return fields


def validate(skill_dir: Path) -> list[str]:
    skill_md = skill_dir / "SKILL.md"
    if not skill_md.exists():
        return ["missing SKILL.md"]
    text = skill_md.read_text(encoding="utf-8")
    fm = parse_frontmatter(text)
    errors = []
    name, desc = fm.get("name", ""), fm.get("description", "")
    if not NAME_RE.match(name) or len(name) > 64:
        errors.append(f"name {name!r}: lowercase letters, digits, hyphens, max 64")
    if any(word in name for word in RESERVED):
        errors.append(f"name {name!r} contains a reserved word")
    if name != skill_dir.name:
        errors.append(f"name {name!r} does not match folder {skill_dir.name!r}")
    if not desc or len(desc) > 1024:
        errors.append("description must be 1-1024 characters")
    if "<" in name + desc:
        errors.append("no XML tags in name or description")
    if "when" not in desc.lower():
        errors.append("warning: description should say when to use the skill")
    body_lines = text.count("\n")
    if body_lines > 500:
        errors.append(f"warning: SKILL.md has {body_lines} lines; split into files")
    return errors


if __name__ == "__main__":
    for path in sys.argv[1:]:
        problems = validate(Path(path))
        print(f"{path}: {'OK' if not problems else '; '.join(problems)}")

Run it in CI over your skills/ folder, next to whatever evaluation tasks you keep for each skill.

8. Security: treat skills like software

A skill is instructions plus code that the agent will follow and run. Anthropic's guidance is direct: "We recommend installing skills only from trusted sources. When installing a skill from a less-trusted source, thoroughly audit it before use." The launch post adds that the feature "gives Claude access to execute code", so be "mindful about which skills you use".

Threats to keep in mind:

Simon Willison's launch-day note applies to all of this: skills depend on a code execution environment, and "the word safe there is doing a lot of work". Run agents with skills in a sandbox or container when they touch anything sensitive.

9. Checklist

• [ ] Does the description say what the skill does and when to use it, in third person?
• [ ] Is name lowercase-hyphenated, under 64 characters, and equal to the folder name?
• [ ] Is SKILL.md under about 500 lines, with details split into linked files?
• [ ] Are all reference files linked directly from SKILL.md?
• [ ] Do fragile steps use scripts with clear error messages?
• [ ] Is there a validation loop for quality-critical output?
• [ ] Are there at least a few evaluation tasks, run with and without the skill?
• [ ] Has every file (Markdown and code) been reviewed by a human?
• [ ] Is the skill versioned in a repository and published to each surface that needs it?

Why this matters

• Know-how becomes a reviewable artifact. Conventions that lived in people's heads or in long prompts become files you can diff, test and share.
• Progressive disclosure keeps context lean. Many skills can be installed while only the relevant one is loaded.
• Scripts make agents more deterministic. The agent decides what to do; tested code does the fragile parts.
• One format, several surfaces. The same folder works in the Claude apps, Claude Code and the API, even if you have to publish it to each.
• Skills are code. The same supply chain discipline you apply to dependencies applies here.

Final Thoughts

Agent Skills are almost boring: a folder, a Markdown file, a bit of YAML. That is the point. They move the effort from clever prompting to writing good internal documentation and small reliable scripts, which teams already know how to review and maintain.

Start with one workflow your team explains to the agent every week. Write the description carefully, keep the body short, put the fragile parts in a script, add a validation step, and test it on real tasks. Then review it like code, because that is what it is.

Sources

• Anthropic, Introducing Agent Skills (October 16, 2025): launch, availability across Claude apps, Claude Code and API, pre-built document skills, skill-creator, code execution caution.
• Anthropic Engineering, Equipping agents for the real world with Agent Skills (October 16, 2025): progressive disclosure levels, required frontmatter, bundled code, onboarding guide analogy, trusted sources guidance.
• Anthropic docs, Agent Skills overview: frontmatter rules, token costs per level, surfaces, Claude Code skill folders, no cross-surface sync, API runtime constraints, security considerations.
• Anthropic docs, Skill authoring best practices: conciseness, third-person descriptions, 500-line guidance, one-level references, degrees of freedom, evaluations first, MCP tool naming.
• Anthropic, anthropics/skills on GitHub: example and document skills, template, plugin marketplace instructions, and the Agent Skills spec (version 1.0 of October 16, 2025; 1.1 of December 16, 2025) with optional license, allowed-tools and metadata fields.
• Anthropic, Claude Cookbooks: skills: beta headers, client.beta.messages.create with container, client.beta.skills.create with files_from_dir.
• Simon Willison, Claude Skills are awesome, maybe a bigger deal than MCP (October 16, 2025): token efficiency vs. MCP, simplicity, dependence on a safe code execution environment.