Jonathon's AI Wiki

Agent Skills Overview (Official Anthropic Docs)

6 min read

Source: Claude Docs Agent Skills Overview 2026 04 17 (Anthropic platform docs — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview.md)

The official reference page for Agent Skills — the authoritative doc on skill format, progressive-disclosure architecture, cross-surface support and limitations, and the security model. Complements the engineering blog Building Agents with Skills (narrative / philosophy) with the structural spec (VM environment, 3-level loading, field requirements, beta headers).

Key Takeaways

  • Skills are filesystem-based, VM-executed. Claude runs in a virtual machine with filesystem, bash, and code execution. Skills are directories on that VM. Claude accesses them via bash — same way you’d navigate files on your machine.
  • Three loading levels (Anthropic’s official numbers — slightly different from the earlier blog’s estimates):
    • Level 1 (Metadata) — always loaded, ~100 tokens per Skill (just name + description from YAML)
    • Level 2 (Instructions) — loaded when Skill triggered, under 5k tokens (SKILL.md body)
    • Level 3+ (Resources) — loaded as needed, effectively unlimited (bundled files executed via bash; code and contents don’t enter context)
  • Scripts are token-free except for output. When Claude runs validate_form.py via bash, the script’s code never loads into context. Only its output (e.g. “Validation passed”) consumes tokens. Makes scripts far more efficient than having Claude generate equivalent code on the fly.
  • YAML field requirements (formal spec):
    • name — max 64 chars, lowercase letters/numbers/hyphens only, no XML tags, cannot contain reserved words “anthropic” or “claude”
    • description — non-empty, max 1024 chars, no XML tags
  • Pre-built Agent Skills: PowerPoint (pptx), Excel (xlsx), Word (docx), PDF (pdf). Available on Claude API and claude.ai.
  • API requires three beta headers to use Skills:
    • code-execution-2025-08-25
    • skills-2025-10-02
    • files-api-2025-04-14
  • NOT ZDR-eligible. Agent Skills is explicitly excluded from Zero Data Retention arrangements. Skill definitions and execution data retained per Anthropic’s standard policy. Contrast with Extended Thinking which is ZDR-eligible.
  • Custom Skills do NOT sync across surfaces. Claude.ai upload ≠ API upload ≠ Claude Code filesystem. Must manage separately on each surface where you want a skill available.
  • Sharing scope differs by surface:
    • Claude.ai — individual user only; no org-wide distribution or centralized admin management
    • Claude API — workspace-wide
    • Claude Code — personal (~/.claude/skills/) or project-based (.claude/skills/); can be shared via Claude Code Plugins
  • Runtime environment differs by surface:
    • Claude.ai — varying network access per user/admin settings
    • Claude API — NO network access, NO runtime package install, pre-configured deps only
    • Claude Code — full network access (same as any program on user’s machine); global package install discouraged
  • Security posture is explicit. Anthropic strongly recommends using Skills only from trusted sources. Malicious skills can direct Claude to misuse tools, leak data, or exfiltrate via external URL dependencies. “Treat like installing software.”

Progressive disclosure — quick reference

LevelWhen loadedToken costWhat
1At startup (always)~100 tokens per Skillname + description YAML
2When Skill triggered< 5k tokensSKILL.md body
3+As referencedEffectively unlimitedAny bundled files — read via bash, scripts executed with output-only into context

Minimal skill structure

pdf-skill/
├── SKILL.md              # Level 1 metadata + Level 2 body
├── FORMS.md              # Level 3, loaded only if form-filling needed
├── REFERENCE.md          # Level 3
└── scripts/
    └── fill_form.py      # Level 3, code never enters context

SKILL.md YAML frontmatter:

---
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 from PDFs:
...

Cross-surface matrix

SurfacePre-built SkillsCustom SkillsSync to other surfacesNetworkCentral admin
Claude.aiYesYes (user-local, Pro+)NoVaries by settingsNo
Claude APIYesYes (workspace-wide)NoNoWorkspace-level
Claude CodeNoYes (filesystem)NoFullVia plugins

API usage pattern

# (Pseudocode; actual usage requires the three beta headers)
response = client.messages.create(
    model="claude-sonnet-4-6",
    tools=[{"type": "code_execution_20250825"}],
    container={"skill_id": "pptx"},
    messages=[...]
)

Pre-built skill IDs: pptx, xlsx, etc. Custom skills uploaded via /v1/skills are shared workspace-wide.

Security checklist

Before using a third-party skill:

  1. Read every file in the skill folder — SKILL.md, reference files, scripts, bundled resources
  2. Look for external URL fetches — dependencies can change and become malicious
  3. Check what tools the skill expects (file ops, bash, code execution) and match against Claude’s current permissions
  4. Verify the skill’s stated purpose matches what its scripts actually do
  5. If you’re uncertain — don’t install. Treat like installing software from an unknown source.

Open Questions

  • Token figures reconciliation. Blog post (Building Agents with Skills) cites ~50 / ~500 / 2,000+ tokens for the three levels; official docs here say ~100 / <5k / effectively-unlimited. Are these different skill sizes or a documentation drift?
  • Custom skill portability tooling. With no sync across surfaces, is there an Anthropic-provided tool to export-import between Claude.ai, API, and Claude Code? Docs imply manual.
  • Non-ZDR scope. What specifically about skills triggers non-ZDR status — is it the code-execution environment, the file-storage of uploaded skills, or something else?
  • Admin controls for Claude.ai. The docs explicitly say Claude.ai has no centralized admin management or org-wide distribution. Is that on the roadmap?
  • Skill-to-skill invocation. Can one skill call another? Implied in the broader blog but not specified in the overview.

Try It

  1. Authoring sanity check. Create a minimal skill folder with a compliant SKILL.md YAML (respect the 64-char name limit, 1024-char description limit, banned reserved words). Drop it in .claude/skills/ and run Claude Code. Confirm the name appears in the metadata when Claude lists available skills.
  2. Exercise the three levels. Author a skill with a SKILL.md that references a separate REFERENCE.md. Ask Claude a question that triggers the skill; then one that triggers the skill AND needs REFERENCE. Observe the difference in token usage between the two interactions.
  3. Test cross-surface non-sync. Author a skill in Claude Code. Verify it does NOT appear in Claude.ai unless separately uploaded. Makes the limitation concrete before shipping anything that depends on it.
  4. Skill security audit template. For any external skill you’re considering, run through the 5-point security checklist above before installing. Build it into your team’s review process.
  5. Migrate a runbook into a skill. Pick an internal runbook that currently lives in a Notion page or README. Convert to a skill with a SKILL.md and any referenced scripts. This is the “enterprise skill” pattern from Building Agents with Skills.

Graph View

Backlinks