17 KiB
Anthropic Agent Skills — Reference Documentation
Extracted from official Anthropic documentation — March 2026. Primary target: claude.ai (Pro, Max, Team, Enterprise plans with code execution enabled). Sources: Agent Skills Overview · Best Practices · Help Center — Creating custom Skills
Table of contents
- What are Skills?
- How Skills work — Progressive disclosure
- Skill structure
- SKILL.md format and frontmatter
- How to upload a Skill to claude.ai
- Runtime environment on claude.ai
- Authoring best practices
- Common patterns
- Workflows and feedback loops
- Security considerations
- Limitations on claude.ai
- Pre-built Agent Skills
- Troubleshooting
1. What are Skills?
Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates, reference files) that Claude uses automatically when relevant.
Key benefits:
- Specialize Claude: Tailor capabilities for domain-specific tasks
- Reduce repetition: Create once, use automatically across conversations
- Compose capabilities: Combine Skills to build complex workflows
Unlike prompts (one-off conversation instructions), Skills load on-demand and eliminate the need to repeatedly provide the same guidance.
On claude.ai, both pre-built and custom Skills are available. Pre-built Skills (PowerPoint, Excel, Word, PDF) work out of the box. Custom Skills are uploaded as .zip files and are available to the uploading user only.
2. How Skills work — Progressive disclosure
Skills load in three stages. Only relevant content occupies the context window at any time.
Level 1 — Metadata (always loaded, ~100 tokens per Skill)
The YAML frontmatter (name + description) is pre-loaded at startup into the system prompt. Claude knows the Skill exists and when to use it — zero token cost until triggered.
Level 2 — Instructions (loaded when triggered, < 5k tokens)
The body of SKILL.md is read from the filesystem when the Skill becomes relevant. This contains procedural knowledge: workflows, best practices, guidance.
Level 3 — Resources (loaded as needed, no practical limit)
Supporting files live on the filesystem and are read only when Claude needs them. Scripts are executed via bash; only the output enters the context window — the script code itself never consumes tokens.
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| 1: Metadata | Always (startup) | ~100 tokens / Skill | name and description from YAML frontmatter |
| 2: Instructions | When Skill is triggered | < 5k tokens | SKILL.md body |
| 3: Resources | As needed | Effectively unlimited | Bundled files and scripts |
Example: loading a Skill
- Startup — system prompt includes:
PDF Processing — Extract text and tables from PDF files - User request — "Extract the text from this PDF"
- Claude reads
pdf-skill/SKILL.md→ instructions loaded into context - Claude determines form filling is not needed →
FORMS.mdis not read - Claude executes the task using
SKILL.mdinstructions
3. Skill structure
Every Skill is a directory with SKILL.md as the required entrypoint.
my-skill/
├── SKILL.md # Required — main instructions
├── reference.md # Optional — detailed reference docs
├── examples.md # Optional — usage examples
└── scripts/
├── analyze.py # Optional — utility scripts (executed, not loaded)
└── validate.py
Pattern: domain-specific organization (for complex Skills)
my-skill/
├── SKILL.md # Overview and navigation
└── reference/
├── topic-a.md
├── topic-b.md
└── topic-c.md
When uploaded to claude.ai, the entire directory is zipped and uploaded as a single .zip file.
4. SKILL.md format and frontmatter
Every SKILL.md starts with YAML frontmatter between --- markers.
Minimal working example
---
name: mechanical-calculations
description: Performs structural calculations, stress analysis, fatigue checks, and beam theory. Use when the user asks for mechanical engineering calculations, sizing of components, or structural verification.
---
# Mechanical Calculations
## Quick start
[Step-by-step instructions for Claude to follow...]
Frontmatter fields
| Field | Required | Description |
|---|---|---|
name |
No* | Slash command name. Lowercase letters, numbers, hyphens only. Max 64 chars. If omitted, uses directory name. |
description |
Recommended | What the Skill does and when to use it. Max 1024 chars. Critical for automatic discovery. |
argument-hint |
No | Hint shown during autocomplete. Example: [component] [load] |
disable-model-invocation |
No | true = only the user can invoke manually. Default: false |
user-invocable |
No | false = hidden from the / menu (Claude-only). Default: true |
Note: Fields
context,agent,hooks,effort,allowed-tools, and string substitutions like$ARGUMENTSare Claude Code features only and have no effect on claude.ai.
Validation rules
name:
- Maximum 64 characters
- Lowercase letters, numbers, and hyphens only
- No XML tags
- Cannot contain the reserved words
anthropicorclaude
description:
- Must be non-empty
- Maximum 1024 characters
- No XML tags
- Always write in third person (it is injected into the system prompt)
Invocation control
| Frontmatter | User can invoke (/name) |
Claude auto-invokes | Description in context |
|---|---|---|---|
| (default) | Yes | Yes | Always present |
disable-model-invocation: true |
Yes | No | Not pre-loaded |
user-invocable: false |
No | Yes | Always present |
Writing effective descriptions
The description is the only signal Claude uses to decide whether to trigger a Skill. Make it specific.
Good:
description: Performs stress analysis, fatigue calculations, and beam theory for mechanical components. Use when the user mentions stress, load, fatigue, section modulus, or asks to verify a mechanical design.
Bad:
description: Helps with mechanical engineering
Rules:
- Write in third person ("Performs…", not "I can…" or "You can…")
- Include what the Skill does
- Include when to use it (list key trigger words)
- Be specific — Claude may have 100+ Skills loaded
5. How to upload a Skill to claude.ai
Step 1 — Build the Skill directory
my-skill/
├── SKILL.md
├── reference/
│ └── guide.md
└── scripts/
└── helper.py
Step 2 — Create the .zip
zip -r my-skill.zip my-skill/ -x "*.DS_Store" -x "*__pycache__*"
Or use the compress-skills.sh script in this repository:
./compress-skills.sh
# Output: dist/my-skill.zip
Step 3 — Upload to claude.ai
- Go to claude.ai → Settings
- Navigate to Features → Skills
- Click Upload skill and select the
.zipfile - Repeat for each Skill
Step 4 — Use the Skill
In any conversation, invoke with a slash command:
/my-skill [optional description of the problem]
Or simply describe your problem — Claude will trigger the Skill automatically if it matches the description.
Requirements
- Plan: Pro, Max, Team, or Enterprise with code execution enabled
- Max upload size: 8 MB per
.zip - The
.zipmust containSKILL.mdat the top level of the skill folder
6. Runtime environment on claude.ai
On claude.ai, Skills run in a code execution container (virtual machine) with:
| Capability | Status on claude.ai |
|---|---|
| Network access | Varies — depends on user/admin settings (may be full, partial, or none) |
| Package installation | Allowed: npm (Node.js), PyPI (Python), GitHub repositories |
| Filesystem access | Yes — Claude can read/write files within the container |
| Bash execution | Yes — scripts are executed via bash |
Important: Scripts can install packages at runtime (unlike the Claude API, which has no network access). Declare all dependencies explicitly in your SKILL.md so Claude installs them before use.
## Dependencies
Install before use:
```bash
pip install pdfplumber pandas
---
## 7. Authoring best practices
### Be concise — context is shared
Only add context Claude doesn't already have. Challenge every line: "Does Claude really need this?"
**Good (~50 tokens):**
```markdown
## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
**Bad (~150 tokens):**
```markdown
## 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...
Set appropriate degrees of freedom
| Constraint level | When to use | How |
|---|---|---|
| High freedom | Multiple valid approaches, context-dependent | Text instructions with guidelines |
| Medium freedom | Preferred pattern exists, some variation OK | Pseudocode or templates |
| Low freedom | Fragile operations, consistency critical | Exact scripts with no parameters |
Naming conventions
Prefer gerund form (verb + -ing) or noun phrases:
processing-pdfs,analyzing-data,calculating-stresspdf-processing,stress-analysis,material-selection- Avoid:
helper,utils,tools, anything containinganthropicorclaude
Progressive disclosure
- Keep
SKILL.mdbody under 500 lines - Move detailed content to supporting files, referenced from
SKILL.md - Keep references one level deep — avoid chains (SKILL.md → a.md → b.md)
- Add a table of contents to reference files longer than 100 lines
## Additional resources
- Complete formula reference → [reference/formulas.md](reference/formulas.md)
- Material properties database → [reference/materials.md](reference/materials.md)
- Worked examples → [examples.md](examples.md)
Use consistent terminology
Choose one term and use it throughout:
- Always "stress" (not stress/tension/load interchangeably)
- Always "section modulus" (not section modulus/Z/W)
- Always "yield strength" (not yield strength/Rp0.2/Sy)
Avoid time-sensitive information
Bad:
If you're using Python before 3.10, use the old syntax.
Good:
## Current method
[current approach]
## Legacy patterns
<details>
<summary>Python < 3.10 (deprecated)</summary>
[old approach]
</details>
8. Common patterns
Pattern 1 — High-level guide with references
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
[...basic extraction code here...]
## Advanced features
- Form filling → [FORMS.md](FORMS.md)
- API reference → [REFERENCE.md](REFERENCE.md)
- Examples → [EXAMPLES.md](EXAMPLES.md)
Pattern 2 — Domain-specific routing
---
name: engineering-data
description: Provides material properties, standards, and formulas for mechanical engineering. Use when the user asks for material data, ISO/ASME standards, or engineering constants.
---
# Engineering Reference Data
## Available datasets
- **Materials** → [reference/materials.md](reference/materials.md)
- **Standards (ISO/ASME/DIN)** → [reference/standards.md](reference/standards.md)
- **Formulas** → [reference/formulas.md](reference/formulas.md)
Pattern 3 — Conditional routing
## Workflow
**New document?** → Follow "Creation workflow" below
**Editing existing?** → Follow "Editing workflow" below
Template pattern
## Report structure
Use this template:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview]
## Key findings
- Finding 1
- Finding 2
## Recommendations
1. Action item
### Examples pattern (input/output pairs)
```markdown
## Output format
**Example 1:**
Input: Calculate stress in M10 bolt with 5 kN axial load
Output:
Bolt M10 — Axial stress analysis Tensile stress area: As = 58.0 mm² Applied force: F = 5000 N Nominal stress: σ = F/As = 86.2 MPa Yield strength (8.8): Rp0.2 = 640 MPa Safety factor: SF = 640/86.2 = 7.4 ✓
9. Workflows and feedback loops
Workflow checklist pattern
Provide a checklist Claude copies into its response and checks off:
## Verification workflow
Copy and track:
Progress:
- Step 1: Identify loads and boundary conditions
- Step 2: Select calculation method
- Step 3: Perform calculations
- Step 4: Check against allowable limits
- Step 5: State safety factor and conclusion
Feedback loop pattern
## Calculation review process
1. Perform calculations
2. **Check immediately**: verify units are consistent throughout
3. If inconsistency found:
- Identify the conversion error
- Correct and recalculate
4. **Only present results when all checks pass**
5. State assumptions and references used
Plan-validate-execute pattern
For complex tasks with many steps:
- Create an intermediate plan/mapping file
- Validate the plan with a script or manual check
- Execute only after validation passes
- Verify the output
10. Security considerations
- Only use Skills from trusted sources — yourself or Anthropic
- Audit all bundled files before use:
SKILL.md, all scripts, all reference files - Skills that fetch external URLs are high risk — fetched content may contain malicious instructions
- Treat like installing software — malicious Skills can misuse file operations, bash, code execution, or exfiltrate data
If you must use a Skill from an unknown source, thoroughly audit it before uploading. Malicious Skills could lead to data exfiltration or unauthorized operations.
11. Limitations on claude.ai
| Constraint | Detail |
|---|---|
| Availability | Pro, Max, Team, Enterprise plans with code execution enabled |
| Sharing scope | Per-user only — each user must upload their own copy; no org-wide distribution |
| Cross-surface sync | Skills uploaded to claude.ai are not available via the API, and vice versa |
| Max zip size | 8 MB |
| Network access | Varies by user/admin settings |
| Advanced frontmatter | Fields context, agent, hooks, effort, string substitutions ($ARGUMENTS, ${CLAUDE_SKILL_DIR}) are Claude Code only — ignored on claude.ai |
12. Pre-built Agent Skills
Available on claude.ai for all users with code execution — no setup required:
| Skill | Capability |
|---|---|
| PowerPoint | Create presentations, edit slides, analyze content |
| Excel | Create spreadsheets, analyze data, generate charts |
| Word | Create and edit documents, format text |
| Generate formatted PDF documents and reports |
These Skills activate automatically when you ask Claude to create or edit the corresponding file type.
13. Troubleshooting
| Problem | Solution |
|---|---|
| Skill not triggering automatically | Check description includes natural-language keywords; try /skill-name directly |
| Skill triggers too often | Make description more specific; add disable-model-invocation: true |
| Upload fails | Verify SKILL.md is at the top level of the folder inside the zip; check zip is < 8 MB |
| Script error: package not found | Declare all dependencies in SKILL.md; claude.ai can install from PyPI/npm at runtime |
| Many Skills loaded but some ignored | Descriptions are capped at ~2% of context window; shorten existing descriptions |