ventz/ai-skills-agents-context / context/creating-a-new-skill
creating-a-new-skill
VerifiedComprehensive Agent Skills Documentation
This document contains ALL the information needed to create effective Agent Skills for Claude Code, Claude.ai, and the Claude Developer Platform.
Agent Skills are now a formal open standard at agentskills.io, adopted by 35+ tools (Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenAI Codex, Goose, Kiro, OpenHands, Letta, Amp, Junie, Databricks Genie, Snowflake Cortex Code, Spring AI, Laravel Boost, Factory, OpenCode, Roo Code, and more). Claude Code implements a superset of the standard — see Agent Skills Open Standard for the spec and the Claude-Code-only extensions.
Table of Contents
- Introduction
- What are Agent Skills?
- How Skills Work
- Core Principles for Creating Skills
- Skill Structure
- Invocation Control
- String Substitutions
- Dynamic Context Injection
- Running Skills in a Subagent 9a. Skill Content Lifecycle (Claude Code) 9b. Reference vs Task Content
- Writing Effective Descriptions
- Progressive Disclosure Patterns
- Workflows and Feedback Loops
- Content Guidelines
- Common Patterns
- Anti-Patterns to Avoid
- Advanced: Skills with Executable Code
- Using Skills Across Platforms
- Bundled Skills (Claude Code)
- Skill Permission Control (Claude Code)
- Evaluation and Iteration
- Security Considerations
- Troubleshooting
- Complete Examples
- Agent Skills Open Standard (agentskills.io)
- Checklist for Effective Skills
Introduction
Agent Skills are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. Skills provide Claude with domain-specific expertise, workflows, context, and best practices that transform general-purpose agents into specialists.
Why Use Skills
Skills are reusable, filesystem-based resources that provide:
- Specialize Claude: Tailor capabilities for domain-specific tasks
- Reduce repetition: Create once, use automatically across multiple conversations
- Compose capabilities: Combine Skills to build complex workflows
- Efficient context usage: Only loads what's needed, when it's needed
- Portable: Same format works across Claude.ai, Claude API, Claude Code, and Claude Agent SDK
Key Characteristics
Skills are:
- Dual-invocable: Both model-invoked (Claude autonomously decides when to use them) AND user-invocable (type
/skill-nameto invoke directly). Frontmatter fields let you restrict to one or the other - Composable: Skills stack together. Claude automatically identifies which skills are needed and coordinates their use
- Portable: Skills use the same format everywhere. Build once, use across Claude apps, Claude Code, and API
- Efficient: Progressive disclosure - only loads what's needed, when it's needed
- Powerful: Skills can include executable code for tasks where traditional programming is more reliable than token generation
Note: Custom commands (
.claude/commands/) have been merged into skills. A file at.claude/commands/review.mdand a skill at.claude/skills/review/SKILL.mdboth create/reviewand work the same way. Your existing.claude/commands/files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and the ability for Claude to load them automatically when relevant. If a skill and a command share the same name, the skill takes precedence.
What are Agent Skills?
Agent Skills package expertise into discoverable capabilities. Each Skill consists of:
- SKILL.md file (required) with YAML frontmatter containing name and description
- Instructions in the body of SKILL.md that Claude reads when relevant
- Optional supporting files like additional markdown documentation, scripts, templates, and resources
Skills leverage Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials.
Skills vs Prompts
| Feature | Skills | Prompts |
|---|---|---|
| Scope | Reusable across conversations | Single conversation |
| Invocation | Both user (/name) and Claude (automatic) | Manual only |
| Loading | On-demand, progressive | All upfront |
| Discovery | Automatic based on metadata | Manual invocation |
| Context | Minimal until triggered | Consumes context immediately |
| Updates | Edit files, changes persist | Re-type each time |
| Code | Can bundle executable scripts | Only generated on-the-fly |
| Arguments | Support $ARGUMENTS substitution | N/A |
How Skills Work
Three Levels of Loading (Progressive Disclosure)
Skills leverage progressive disclosure: Claude loads information in stages as needed, rather than consuming context upfront.
Level 1: Metadata (always loaded)
Content type: Instructions. The Skill's YAML frontmatter provides discovery information:
---
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.
---
Claude loads this metadata at startup and includes it in the system prompt. This lightweight approach means you can install many Skills without context penalty; Claude only knows each Skill exists and when to use it.
Token cost: ~100 tokens per Skill
Level 2: Instructions (loaded when triggered)
Content type: Instructions. The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance.
When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem via bash. Only then does this content enter the context window.
Token cost: Under 5k tokens (keep SKILL.md body under 500 lines)
Level 3: Resources and Code (loaded as needed)
Content types: Instructions, code, and resources. Skills can bundle additional materials:
pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed API reference)
└── scripts/
└── fill_form.py (utility script)
- Instructions: Additional markdown files containing specialized guidance and workflows
- Code: Executable scripts that Claude runs via bash; scripts provide deterministic operations without consuming context
- Resources: Reference materials like database schemas, API documentation, templates, or examples
Claude accesses these files only when referenced.
Token cost: Effectively unlimited. Files executed via bash don't load into context; only output consumes tokens.
| Level | When Loaded | Token Cost | Content |
|---|---|---|---|
| Level 1: Metadata | Always (at startup) | ~100 tokens per Skill | name and description from YAML frontmatter |
| Level 2: Instructions | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| Level 3+: Resources | As needed | Effectively unlimited | Bundled files executed via bash without loading contents into context |
The Skills Architecture
Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities.
How Claude accesses Skill content:
- Metadata pre-loaded: At startup, name and description from all Skills' YAML frontmatter are loaded into the system prompt
- Files read on-demand: Claude uses bash to access SKILL.md and other files from the filesystem when needed
- Scripts executed efficiently: Utility scripts can be executed via bash without loading their full contents into context. Only the script's output consumes tokens
- No context penalty for large files: Reference files, data, or documentation don't consume context tokens until actually read
What this architecture enables:
- On-demand file access: Claude reads only the files needed for each specific task
- Efficient script execution: When Claude runs
validate_form.py, the script's code never loads into the context window. Only the script's output consumes tokens - No practical limit on bundled content: Because files don't consume context until accessed, Skills can include comprehensive documentation, large datasets, extensive examples, or any reference materials
Example: Loading a PDF Processing Skill
Here's how Claude loads and uses a PDF processing skill:
- Startup: System prompt includes:
PDF Processing - Extract text and tables from PDF files, fill forms, merge documents - User request: "Extract the text from this PDF and summarize it"
- Claude invokes:
bash: read pdf-skill/SKILL.md→ Instructions loaded into context - Claude determines: Form filling is not needed, so FORMS.md is not read
- Claude executes: Uses instructions from SKILL.md to complete the task
Only relevant content occupies the context window at any given time.
Core Principles for Creating Skills
1. Concise is Key
The context window is a public good. Your Skill shares it with everything else Claude needs to know.
Default assumption: Claude is already very smart. Only add context Claude doesn't already have.
Challenge each piece of information:
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"
Good example: Concise (approximately 50 tokens):
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
Bad example: Too verbose (approximately 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 and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
2. Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability.
High freedom (text-based instructions):
- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach
Medium freedom (pseudocode or scripts with parameters):
- A preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior
Low freedom (specific scripts, few or no parameters):
- Operations are fragile and error-prone
- Consistency is critical
- A specific sequence must be followed
Analogy: Think of Claude as a robot exploring a path:
- Narrow bridge with cliffs: Only one safe way forward. Provide specific guardrails (low freedom)
- Open field: Many paths lead to success. Give general direction and trust Claude (high freedom)
3. Test with All Models You Plan to Use
Skills act as additions to models, so effectiveness depends on the underlying model. Test with:
- Claude Haiku (fast, economical): Does the Skill provide enough guidance?
- Claude Sonnet (balanced): Is the Skill clear and efficient?
- Claude Opus (powerful reasoning): Does the Skill avoid over-explaining?
4. Build Evaluations First
Create evaluations BEFORE writing extensive documentation. This ensures your Skill solves real problems.
Evaluation-driven development:
- Identify gaps: Run Claude on representative tasks without a Skill. Document specific failures or missing context
- Create evaluations: Build three scenarios that test these gaps
- Establish baseline: Measure Claude's performance without the Skill
- Write minimal instructions: Create just enough content to address the gaps and pass evaluations
- Iterate: Execute evaluations, compare against baseline, and refine
Skill Structure
Basic Directory Structure
my-skill/
├── SKILL.md (required)
├── reference.md (optional documentation)
├── examples.md (optional examples)
├── scripts/
│ └── helper.py (optional utility)
└── templates/
└── template.txt (optional template)
SKILL.md Format
Every Skill requires a SKILL.md file with YAML frontmatter:
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]
YAML Frontmatter Reference
All fields are optional. Only description is recommended so Claude knows when to use the skill.
| Field | Required | Description |
|---|---|---|
name | No | Display name for the skill. If omitted, uses the directory name. 1–64 chars, lowercase a-z, digits, hyphens only. No leading/trailing hyphen, no consecutive --. Must match the parent directory name. |
description | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph. Claude Code: description + when_to_use combined is capped at 1,536 chars (tunable via maxSkillDescriptionChars). agentskills.io standard: description alone capped at 1,024 chars. Front-load the key use case. |
when_to_use | No | (Claude Code) Additional trigger phrases / example requests, appended to description in the skill listing. Counts toward the 1,536-char cap. |
argument-hint | No | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format]. |
arguments | No | (Claude Code) Named positional arguments for $name substitution. Space-separated string or YAML list; names map to positions in order. |
disable-model-invocation | No | Set to true to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with /name. Also prevents preloading into subagents. Default: false. |
user-invocable | No | Set to false to hide from the / menu. Use for background knowledge users shouldn't invoke directly. Default: true. |
allowed-tools | No | Tools Claude can use without per-use approval when this skill is active. Space-separated string or YAML list. For project skills, takes effect only after workspace trust is accepted. |
model | No | (Claude Code) Model to use when this skill is active. Per-turn override, not persisted. Accepts /model values or inherit to keep the active model. |
effort | No | (Claude Code) Effort level: low, medium, high, xhigh, max (availability depends on model). Overrides session effort while skill is active. |
context | No | (Claude Code) Set to fork to run in a forked subagent context. See Running Skills in a Subagent. |
agent | No | (Claude Code) Which subagent type to use when context: fork is set. Built-in (Explore, Plan, general-purpose) or custom from .claude/agents/. |
hooks | No | (Claude Code) Hooks scoped to this skill's lifecycle. See Claude Code hooks documentation. |
paths | No | (Claude Code) Glob patterns that limit auto-activation. Comma-separated string or YAML list. When set, Claude auto-loads the skill only when working with matching files. Same format as path-specific rules. |
shell | No | (Claude Code) Shell for !`cmd` and ```! blocks: bash (default) or powershell. PowerShell requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1. |
license | No | (agentskills.io standard) License name or reference to a bundled license file. |
compatibility | No | (agentskills.io standard) Environment requirements (intended product, system packages, network access). Max 500 chars. |
metadata | No | (agentskills.io standard) Arbitrary string→string map for additional metadata not in the spec. |
Full example with all optional fields:
---
name: deploy
description: Deploy the application to production
argument-hint: [environment]
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
context: fork
agent: general-purpose
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
Field validation for name:
- 1–64 characters
- Lowercase
a-z, digits, and hyphens only - No leading or trailing hyphen
- No consecutive hyphens (
--) - Must match the parent directory name
- Cannot contain XML tags
Field validation for description:
- agentskills.io standard: max 1,024 characters
- Claude Code:
description + when_to_usecombined max 1,536 chars (tunable viamaxSkillDescriptionChars) - Cannot contain XML tags
- Should include both what the Skill does AND when Claude should use it
- Front-load the key use case — text is truncated to fit the listing budget
Naming Conventions
Use consistent naming patterns. Recommended: gerund form (verb + -ing).
Good naming examples (gerund form):
processing-pdfsanalyzing-spreadsheetsmanaging-databasestesting-codewriting-documentation
Acceptable alternatives:
- Noun phrases:
pdf-processing,spreadsheet-analysis - Action-oriented:
process-pdfs,analyze-spreadsheets
Avoid:
- Vague names:
helper,utils,tools - Overly generic:
documents,data,files - Reserved words:
anthropic-helper,claude-tools - Inconsistent patterns within your skill collection
Invocation Control
By default, both you and Claude can invoke any skill. You can type /skill-name to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:
Three Invocation Modes
Default (both user and Claude can invoke):
Best for general-purpose skills like code explanations, analysis tools, or reference knowledge. Both /skill-name and automatic invocation work.
disable-model-invocation: true (only user can invoke):
Use for workflows with side effects or that you want to control timing: deploy, commit, send-slack-message, database migrations. You don't want Claude deciding to deploy because your code looks ready.
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
user-invocable: false (only Claude can invoke):
Use for background knowledge that isn't actionable as a command. A legacy-system-context skill explains how an old system works. Claude should know this when relevant, but /legacy-system-context isn't a meaningful action for users to take.
---
name: legacy-system-context
description: Context about the legacy billing system architecture. Use when working with billing code or migrating from the old system.
user-invocable: false
---
Invocation Matrix
| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
|---|---|---|---|
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
disable-model-invocation: true | Yes | No | Description not in context, full skill loads when user invokes |
user-invocable: false | No | Yes | Description always in context, full skill loads when invoked |
Note: In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked.
String Substitutions
Skills support string substitution for dynamic values in the skill content. Arguments are passed when invoking a skill (e.g., /fix-issue 123).
Available Variables
| Variable | Description |
|---|---|
$ARGUMENTS | All arguments passed when invoking the skill. If $ARGUMENTS is not present in the content, arguments are appended as ARGUMENTS: <value>. |
$ARGUMENTS[N] | Access a specific argument by 0-based index, such as $ARGUMENTS[0] for the first argument. |
$N | Shorthand for $ARGUMENTS[N], such as $0 for the first argument or $1 for the second. |
$name | Named positional argument declared in the arguments frontmatter. With arguments: [issue, branch], $issue = first arg, $branch = second. |
${CLAUDE_SESSION_ID} | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |
${CLAUDE_EFFORT} | The current effort level (low, medium, high, xhigh, max). Use to adapt skill instructions to the active effort setting. |
${CLAUDE_SKILL_DIR} | Directory containing the skill's SKILL.md. For plugin skills, the skill's subdirectory within the plugin (not the plugin root). Use this in bash injection commands and script paths so they resolve regardless of cwd. |
Indexed arguments use shell-style quoting: /my-skill "hello world" second → $0 = hello world, $1 = second. $ARGUMENTS always expands to the full raw argument string.
Example: Using ${CLAUDE_SKILL_DIR} for bundled scripts
---
name: codebase-visualizer
description: Generate an interactive HTML tree of the codebase
allowed-tools: Bash(python3 *)
---
Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .`
This resolves correctly whether the skill lives at the personal, project, or plugin level.
Example: Fix a GitHub Issue
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit
When you run /fix-issue 123, Claude receives "Fix GitHub issue 123 following our coding standards..."
Example: Positional Arguments
---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.
Running /migrate-component SearchBar React Vue replaces $ARGUMENTS[0] with SearchBar, $ARGUMENTS[1] with React, and $ARGUMENTS[2] with Vue.
The same skill using the $N shorthand:
---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.
Example: Session Logging
---
name: session-logger
description: Log activity for this session
---
Log the following to logs/${CLAUDE_SESSION_ID}.log:
$ARGUMENTS
Note: If you invoke a skill with arguments but the skill doesn't include
$ARGUMENTS, Claude Code appendsARGUMENTS: <your input>to the end of the skill content so Claude still sees what you typed.
Dynamic Context Injection
The !`command` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.
This is preprocessing, not something Claude executes. Claude only sees the final result.
Example: PR Summary Skill
This skill summarizes a pull request by fetching live PR data with the GitHub CLI:
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`
## Your task
Summarize this pull request. Include:
1. What changed and why
2. Key files affected
3. Potential risks or concerns
When this skill runs:
- Each
!`command`executes immediately (before Claude sees anything) - The output replaces the placeholder in the skill content
- Claude receives the fully-rendered prompt with actual PR data
Multi-Line Shell Injection
For multi-line commands, use a fenced code block opened with ```! instead of the inline form:
## Environment
```!
node --version
npm --version
git status --short
```
Disabling Shell Injection
Set "disableSkillShellExecution": true in settings to block !`cmd` and ```! execution from user/project/plugin/--add-dir skills. Each command is replaced with [shell command execution disabled by policy]. Bundled and managed skills are unaffected. Most useful in managed settings where users cannot override it.
Running Skills in a Subagent
Add context: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. The subagent won't have access to your conversation history.
Important:
context: forkonly makes sense for skills with explicit task instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.
Example: Research Skill
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
When this skill runs:
- A new isolated context is created
- The subagent receives the skill content as its prompt ("Research $ARGUMENTS thoroughly...")
- The
agentfield determines the execution environment (model, tools, and permissions) - Results are summarized and returned to your main conversation
The agent field specifies which subagent configuration to use. Options include built-in agents (Explore, Plan, general-purpose) or any custom subagent from .claude/agents/. If omitted, uses general-purpose.
Skills vs Subagents Comparison
Skills with context: fork and subagents work together in two directions:
| Approach | System prompt | Task | Also loads |
|---|---|---|---|
Skill with context: fork | From agent type (Explore, Plan, etc.) | SKILL.md content | CLAUDE.md |
Subagent with skills field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md |
With context: fork, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see the Claude Code subagents documentation.
When to Use context: fork
- Isolation needed: The skill's work shouldn't pollute your conversation context
- Explicit task: The skill defines a complete, self-contained task
- Parallel execution: Multiple forked skills can run concurrently
- Specialized tools: The agent type provides appropriate tools for the task
Skill Content Lifecycle (Claude Code)
When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays for the rest of the session. Claude Code does not re-read the skill file on later turns.
Implication: Write guidance that should apply throughout a task as standing instructions, not one-time steps.
Auto-Compaction Behavior
When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary:
- Keeps the first 5,000 tokens of each re-attached skill
- Combined re-attachment budget: 25,000 tokens total
- Filled most-recently-invoked first; older skills may be dropped entirely if you invoked many
Debugging "Skill Stopped Working"
If a skill seems to stop influencing behavior after the first response:
- The content is usually still present — the model is choosing other tools/approaches
- Strengthen the skill's
descriptionand instructions so the model keeps preferring it - Use hooks to enforce behavior deterministically
- If the skill is large or many others were invoked after it, re-invoke after compaction to restore the full content
Reference vs Task Content
Two patterns for SKILL.md content. Choose based on how you want it invoked and where it runs.
Reference Content (inline, model-invocable)
Knowledge Claude applies alongside your conversation: conventions, patterns, style guides, domain knowledge. Runs inline with conversation context.
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation
Task Content (action, usually user-only)
Step-by-step instructions for a specific action: deploy, commit, code-generation pipelines. Often paired with disable-model-invocation: true and frequently context: fork.
---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target
Writing Effective Descriptions
The description field enables Skill discovery and should include both what the Skill does and when to use it.
Critical Rules
Always write in third person. The description is injected into the system prompt.
- Good: "Processes Excel files and generates reports"
- Avoid: "I can help you process Excel files"
- Avoid: "You can use this to process Excel files"
Be specific and include key terms. Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills.
Effective Examples
PDF Processing skill:
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.
Excel Analysis skill:
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
Git Commit Helper skill:
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
Bad Examples (Too Vague)
description: Helps with documents
description: Processes data
description: Does stuff with files
Progressive Disclosure Patterns
SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide.
Practical Guidance
- Keep SKILL.md body under 500 lines for optimal performance
- Split content into separate files when approaching this limit
- Use the patterns below to organize instructions, code, and resources effectively
Pattern 1: High-Level Guide with References
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
Pattern 2: Domain-Specific Organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context.
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
├── finance.md (revenue, billing metrics)
├── sales.md (opportunities, pipeline)
├── product.md (API usage, features)
└── marketing.md (campaigns, attribution)
# BigQuery Data Analysis
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
Pattern 3: Conditional Details
Show basic content, link to advanced content:
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
Avoid Deeply Nested References
Claude may partially read files when they're referenced from other referenced files.
Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
Bad example: Too deep:
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)...
# details.md
Here's the actual information...
Good example: One level deep:
# SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
Structure Longer Reference Files with Table of Contents
For reference files longer than 100 lines, include a table of contents at the top.
Example:
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and setup
...
## Core methods
...
Workflows and Feedback Loops
Use Workflows for Complex Tasks
Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy and check off as it progresses.
Example 1: Research synthesis workflow (for Skills without code):
## Research synthesis workflow
Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
**Step 2: Identify key themes**
Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
**Step 3: Cross-reference claims**
For each major claim, verify it appears in the source material. Note which source supports each point.
**Step 4: Create structured summary**
Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)
**Step 5: Verify citations**
Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
Example 2: PDF form filling workflow (for Skills with code):
## PDF form filling workflow
Copy this checklist and check off items as you complete them:
```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```
**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`
This extracts form fields and their locations, saving to `fields.json`.
**Step 2: Create field mapping**
Edit `fields.json` to add values for each field.
**Step 3: Validate mapping**
Run: `python scripts/validate_fields.py fields.json`
Fix any validation errors before continuing.
**Step 4: Fill the form**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify output**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
Implement Feedback Loops
Common pattern: Run validator → fix errors → repeat
This pattern greatly improves output quality.
Example 1: Style guide compliance (for Skills without code):
## Content review process
1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
- Check terminology consistency
- Verify examples follow the standard format
- Confirm all required sections are present
3. If issues found:
- Note each issue with specific section reference
- Revise the content
- Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document
Example 2: Document editing process (for Skills with code):
## Document editing process
1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review the error message carefully
- Fix the issues in the XML
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document
Content Guidelines
Avoid Time-Sensitive Information
Don't include information that will become outdated.
Bad example: Time-sensitive (will become wrong):
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
Good example (use "old patterns" section):
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
Use Consistent Terminology
Choose one term and use it throughout the Skill:
Good - Consistent:
- Always "API endpoint"
- Always "field"
- Always "extract"
Bad - Inconsistent:
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
Use Forward Slashes for Paths
Always use forward slashes in file paths, even on Windows:
- ✓ Good:
scripts/helper.py,reference/guide.md - ✗ Avoid:
scripts\helper.py,reference\guide.md
Unix-style paths work across all platforms.
Common Patterns
Template Pattern
Provide templates for output format. Match the level of strictness to your needs.
For strict requirements (like API responses or data formats):
## Report structure
ALWAYS use this exact template structure:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data
## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
For flexible guidance (when adaptation is useful):
## Report structure
Here is a sensible default format, but use your best judgment based on the analysis:
```markdown
# [Analysis Title]
## Executive summary
[Overview]
## Key findings
[Adapt sections based on what you discover]
## Recommendations
[Tailor to the specific context]
```
Adjust sections as needed for the specific analysis type.
Examples Pattern
For Skills where output quality depends on seeing examples, provide input/output pairs:
## Commit message format
Generate commit messages following these examples:
**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
```
**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling
- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```
Follow this style: type(scope): brief description, then detailed explanation.
Conditional Workflow Pattern
Guide Claude through decision points:
## Document modification workflow
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow" below
**Editing existing content?** → Follow "Editing workflow" below
2. Creation workflow:
- Use docx-js library
- Build document from scratch
- Export to .docx format
3. Editing workflow:
- Unpack existing document
- Modify XML directly
- Validate after each change
- Repack when complete
If workflows become large or complicated with many steps, consider pushing them into separate files.
Anti-Patterns to Avoid
Don't Offer Too Many Options
Don't present multiple approaches unless necessary:
**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
Don't Assume Tools are Installed
Don't assume packages are available:
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`
Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"
Don't Use Windows-Style Paths
Always use forward slashes:
- ✓ Good:
scripts/helper.py,reference/guide.md - ✗ Avoid:
scripts\helper.py,reference\guide.md
Advanced: Skills with Executable Code
Solve, Don't Punt
When writing scripts for Skills, handle error conditions rather than punting to Claude.
Good example: Handle errors explicitly:
def process_file(path):
"""Process a file, creating it if it doesn't exist."""
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
# Create file with default content instead of failing
print(f"File {path} not found, creating default")
with open(path, 'w') as f:
f.write('')
return ''
except PermissionError:
# Provide alternative instead of failing
print(f"Cannot access {path}, using default")
return ''
Bad example: Punt to Claude:
def process_file(path):
# Just fail and let Claude figure it out
return open(path).read()
No "Voodoo Constants"
Configuration parameters should be justified and documented.
Good example: Self-documenting:
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
Bad example: Magic numbers:
TIMEOUT = 47 # Why 47?
RETRIES = 5 # Why 5?
Provide Utility Scripts
Even if Claude could write a script, pre-made scripts offer advantages:
Benefits of utility scripts:
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses
Make execution intent clear:
- "Run
analyze_form.pyto extract fields" (execute) - "See
analyze_form.pyfor the extraction algorithm" (read as reference)
Example:
## Utility scripts
**analyze_form.py**: Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```
Output format:
```json
{
"field_name": {"type": "text", "x": 100, "y": 200},
"signature": {"type": "sig", "x": 150, "y": 500}
}
```
**validate_boxes.py**: Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```
**fill_form.py**: Apply field values to PDF
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
Use Visual Analysis
When inputs can be rendered as images, have Claude analyze them:
## Form layout analysis
1. Convert PDF to images:
```bash
python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
Claude's vision capabilities help understand layouts and structures.
Create Verifiable Intermediate Outputs
When Claude performs complex, open-ended tasks, use the "plan-validate-execute" pattern.
Example: Asking Claude to update 50 form fields in a PDF based on a spreadsheet.
Solution: Use the workflow pattern, but add an intermediate changes.json file that gets validated before applying changes. The workflow becomes: analyze → create plan file → validate plan → execute → verify.
Why this pattern works:
- Catches errors early: Validation finds problems before changes are applied
- Machine-verifiable: Scripts provide objective verification
- Reversible planning: Claude can iterate on the plan without touching originals
- Clear debugging: Error messages point to specific problems
When to use: Batch operations, destructive changes, complex validation rules, high-stakes operations.
Implementation tip: Make validation scripts verbose with specific error messages like "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed"
Package Dependencies
Skills run in the code execution environment with platform-specific limitations:
- claude.ai: Can install packages from npm and PyPI and pull from GitHub repositories
- Anthropic API: Has no network access and no runtime package installation
List required packages in your SKILL.md and verify they're available in the code execution tool documentation.
MCP Tool References
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.
Format: ServerName:tool_name
Example:
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
Where:
BigQueryandGitHubare MCP server namesbigquery_schemaandcreate_issueare the tool names within those servers
Extended Thinking in Skills
To enable extended thinking (thinking mode) in a skill, include the word "ultrathink" anywhere in your skill content. This activates Claude's extended thinking capabilities for more complex reasoning tasks.
Using Skills Across Platforms
Where Skills Work
Skills are available across Claude's agent products:
- Claude API: Pre-built Skills (pptx, xlsx, docx, pdf) and custom Skills via
/v1/skillsendpoints - Claude.ai: Pre-built Skills (automatic) and custom Skills (upload via Settings)
- Claude Code: Custom Skills only (filesystem-based)
- Claude Agent SDK: Custom Skills via filesystem configuration
Claude API
The Claude API supports both pre-built Agent Skills and custom Skills.
Prerequisites: Three beta headers required:
code-execution-2025-08-25- Skills run in the code execution containerskills-2025-10-02- Enables Skills functionalityfiles-api-2025-04-14- Required for uploading/downloading files to/from the container
Quick example (Python):
import anthropic
client = anthropic.Anthropic()
# Create a message with the PowerPoint Skill
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": "pptx",
"version": "latest"
}
]
},
messages=[{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides"
}],
tools=[{
"type": "code_execution_20250825",
"name": "code_execution"
}]
)
Pre-built Skills available:
- PowerPoint (pptx): Create presentations, edit slides, analyze content
- Excel (xlsx): Create spreadsheets, analyze data, generate reports with charts
- Word (docx): Create documents, edit content, format text
- PDF (pdf): Generate formatted PDF documents and reports
Custom Skills: Upload via /v1/skills endpoints. Shared organization-wide.
Claude.ai
Pre-built Agent Skills: Working behind the scenes when you create documents. No setup required.
Custom Skills: Upload as zip files through Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled.
Note: Custom Skills are individual to each user; not shared organization-wide.
Claude Code
Custom Skills only. Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically. Users can also invoke skills directly via /skill-name.
Skill Locations and Priority:
Where you store a skill determines who can use it. When skills share the same name across levels, higher-priority locations win:
| Location | Path | Applies to | Priority |
|---|---|---|---|
| Enterprise | Via managed settings | All users in your organization | Highest |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects | High |
| Project | .claude/skills/<skill-name>/SKILL.md | This project only | Normal |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Where plugin is enabled | Namespaced |
Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels.
Enterprise Skills
Deployed organization-wide through managed settings. Highest priority. See Claude Code managed settings documentation.
Personal Skills
Location: ~/.claude/skills/
mkdir -p ~/.claude/skills/my-skill-name
Use for:
- Individual workflows and preferences
- Experimental Skills you're developing
- Personal productivity tools
Project Skills
Location: .claude/skills/ (within your project)
mkdir -p .claude/skills/my-skill-name
Use for:
- Team workflows and conventions
- Project-specific expertise
- Shared utilities and scripts
Project Skills are checked into git and automatically available to team members.
Plugin Skills
Skills can also come from Claude Code plugins. Plugins may bundle Skills that are automatically available when the plugin is installed. Plugin skills are namespaced as plugin-name:skill-name.
Live Change Detection
Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under ~/.claude/skills/, the project .claude/skills/, or an --add-dir'd .claude/skills/ takes effect within the current session without restarting.
Exception: creating a top-level skills directory that did not exist when the session started requires restarting Claude Code so the new directory can be watched.
Nested Directory Discovery (Monorepo Support)
When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories. For example, editing packages/frontend/foo.ts also pulls in skills from packages/frontend/.claude/skills/. Supports monorepo setups where packages have their own skills.
Skills from Additional Directories (--add-dir)
--add-dir grants file access, not configuration discovery. Skills are an exception: .claude/skills/ within an added directory is loaded automatically and benefits from live change detection.
Other .claude/ configuration (subagents, commands, output styles) is not loaded from --add-dir directories. CLAUDE.md files from added directories are also not loaded by default — set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 to opt in.
Claude Agent SDK
The Claude Agent SDK supports custom Skills through filesystem-based configuration.
Create Skills as directories with SKILL.md files in .claude/skills/. Enable Skills by including "Skill" in your allowed_tools configuration.
Cross-Surface Availability
Custom Skills do not sync across surfaces. Skills uploaded to one surface are not automatically available on others:
- Skills uploaded to Claude.ai must be separately uploaded to the API
- Skills uploaded via the API are not available on Claude.ai
- Claude Code Skills are filesystem-based and separate from both
Sharing Scope
- Claude.ai: Individual user only; each team member must upload separately
- Claude API: Workspace-wide; all workspace members can access uploaded Skills
- Claude Code: Personal (
~/.claude/skills/) or project-based (.claude/skills/)
Runtime Environment Constraints
Claude.ai:
- Varying network access: Depending on user/admin settings, Skills may have full, partial, or no network access
Claude API:
- No network access: Skills cannot make external API calls or access the internet
- No runtime package installation: Only pre-installed packages are available
- Pre-configured dependencies only: Check the code execution tool documentation for available packages
Claude Code:
- Full network access: Skills have the same network access as any other program on the user's computer
- Global package installation discouraged: Skills should only install packages locally
Bundled Skills (Claude Code)
Bundled skills ship with Claude Code and are available in every session. Unlike built-in commands (like /help, /compact), which execute fixed logic directly, bundled skills are prompt-based: they give Claude a detailed playbook and let it orchestrate the work using its tools. This means bundled skills can spawn parallel agents, read files, and adapt to your codebase.
You invoke bundled skills the same way as any other skill: type / followed by the skill name.
/simplify
Reviews your recently changed files for code reuse, quality, and efficiency issues, then fixes them. Run it after implementing a feature or bug fix to clean up your work. It spawns three review agents in parallel (code reuse, code quality, efficiency), aggregates their findings, and applies fixes. Pass optional text to focus on specific concerns:
/simplify focus on memory efficiency
/batch <instruction>
Orchestrates large-scale changes across a codebase in parallel. Provide a description of the change and /batch researches the codebase, decomposes the work into 5 to 30 independent units, and presents a plan for your approval. Once approved, it spawns one background agent per unit, each in an isolated git worktree. Each agent implements its unit, runs tests, and opens a pull request. Requires a git repository.
/batch migrate src/ from Solid to React
/debug [description]
Troubleshoots your current Claude Code session by reading the session debug log. Optionally describe the issue to focus the analysis.
/debug why did the last tool call fail?
/loop <interval> <prompt>
Run a prompt or slash command on a recurring interval (e.g. /loop 5m /check-deploys). Omit the interval to let the model self-pace. Useful for polling, status checks, or repeated tasks.
/claude-api
Build, debug, and optimize Claude API / Anthropic SDK applications. Auto-activates when code imports anthropic or @anthropic-ai/sdk. Handles caching, thinking, compaction, tool use, batch, files, citations, memory, and model migrations.
Built-In Commands Also Reachable Via Skill Tool
A few built-in commands are exposed through the Skill tool and respond to Skill(name) permission rules: /init, /review, /security-review. Others like /compact are not.
Note: Claude Code also includes a bundled developer platform skill that activates automatically when your code imports the Anthropic SDK. You don't need to invoke it manually.
Skill Permission Control (Claude Code)
By default, Claude can invoke any skill that doesn't have disable-model-invocation: true set. Skills that define allowed-tools grant Claude access to those tools without per-use approval when the skill is active. Your permission settings still govern baseline approval behavior for all other tools.
Three Ways to Control Skill Access
1. Disable all skills by denying the Skill tool in /permissions:
# Add to deny rules:
Skill
2. Allow or deny specific skills using permission rules:
# Allow only specific skills
Skill(commit)
Skill(review-pr *)
# Deny specific skills
Skill(deploy *)
Permission syntax: Skill(name) for exact match, Skill(name *) for prefix match with any arguments.
3. Hide individual skills by adding disable-model-invocation: true to their frontmatter. This removes the skill from Claude's context entirely.
Note: The
user-invocablefield only controls menu visibility, not Skill tool access. Usedisable-model-invocation: trueto block programmatic invocation.
Skill Visibility Overrides (skillOverrides)
The skillOverrides setting controls skill visibility from settings instead of the skill's own frontmatter. Useful for skills you don't want to (or can't) edit — shared repo skills, MCP-server-provided skills. Set interactively via the /skills menu (Space cycles state, Enter saves to .claude/settings.local.json).
Four states per skill:
| Value | Listed to Claude | In / menu |
|---|---|---|
"on" (default if absent) | Name and description | Yes |
"name-only" | Name only (description hidden — frees budget) | Yes |
"user-invocable-only" | Hidden | Yes |
"off" | Hidden | Hidden |
{
"skillOverrides": {
"legacy-context": "name-only",
"deploy": "off"
}
}
Plugin skills are not affected by skillOverrides — manage those through /plugin.
Evaluation and Iteration
Build Evaluations First
Create evaluations BEFORE writing extensive documentation. This ensures your Skill solves real problems.
Evaluation-driven development:
- Identify gaps: Run Claude on representative tasks without a Skill. Document specific failures or missing context
- Create evaluations: Build three scenarios that test these gaps
- Establish baseline: Measure Claude's performance without the Skill
- Write minimal instructions: Create just enough content to address the gaps and pass evaluations
- Iterate: Execute evaluations, compare against baseline, and refine
Evaluation structure:
{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
"Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
"Extracts text content from all pages in the document without missing any pages",
"Saves the extracted text to a file named output.txt in a clear, readable format"
]
}
Develop Skills Iteratively with Claude
Work with one instance of Claude ("Claude A") to create a Skill that will be used by other instances ("Claude B").
Creating a new Skill:
- Complete a task without a Skill: Work through a problem with Claude A using normal prompting
- Identify the reusable pattern: After completing the task, identify what context you provided that would be useful for similar future tasks
- Ask Claude A to create a Skill: "Create a Skill that captures this BigQuery analysis pattern we just used"
- Review for conciseness: Check that Claude A hasn't added unnecessary explanations
- Improve information architecture: Ask Claude A to organize content more effectively
- Test on similar tasks: Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases
- Iterate based on observation: If Claude B struggles, return to Claude A with specifics
Iterating on existing Skills:
- Use the Skill in real workflows: Give Claude B (with the Skill loaded) actual tasks, not test scenarios
- Observe Claude B's behavior: Note where it struggles, succeeds, or makes unexpected choices
- Return to Claude A for improvements: Share the current SKILL.md and describe what you observed
- Review Claude A's suggestions: Claude A might suggest reorganizing, using stronger language, or restructuring
- Apply and test changes: Update the Skill with Claude A's refinements, then test again with Claude B
- Repeat based on usage: Continue this observe-refine-test cycle as you encounter new scenarios
Why this approach works: Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior.
Observe How Claude Navigates Skills
As you iterate on Skills, pay attention to how Claude actually uses them:
- Unexpected exploration paths: Does Claude read files in an order you didn't anticipate?
- Missed connections: Does Claude fail to follow references to important files?
- Overreliance on certain sections: If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md
- Ignored content: If Claude never accesses a bundled file, it might be unnecessary or poorly signaled
Security Considerations
We strongly recommend using Skills only from trusted sources: those you created yourself or obtained from Anthropic.
Skills provide Claude with new capabilities through instructions and code. A malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.
Key Security Considerations
Audit thoroughly: Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns like unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose.
External sources are risky: Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time.
Tool misuse: Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways.
Data exposure: Skills with access to sensitive data could be designed to leak information to external systems.
Treat like installing software: Only use Skills from trusted sources. Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations.
Warning: If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
Troubleshooting
Claude Doesn't Use My Skill
Check 1: Is the description specific enough?
Include both what the Skill does and when to use it, with key terms users would mention.
Too generic:
description: Helps with data
Specific:
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
Check 2: Is the YAML valid?
# View frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15
# Common issues:
# - Missing opening or closing ---
# - Tabs instead of spaces
# - Unquoted strings with special characters
Check 3: Is the Skill in the correct location?
# Personal Skills
ls ~/.claude/skills/*/SKILL.md
# Project Skills
ls .claude/skills/*/SKILL.md
Skill Has Errors
Check 1: Are dependencies available?
Claude will automatically install required dependencies (or ask for permission).
Check 2: Do scripts have execute permissions?
chmod +x .claude/skills/my-skill/scripts/*.py
Check 3: Are file paths correct?
Use forward slashes (Unix style): scripts/helper.py
Not Windows style: scripts\helper.py
Skill Descriptions Are Cut Short
Skill names are always included in context, but descriptions are shortened to fit a character budget when you have many skills. The budget defaults to 1% of the model's context window. When it overflows, descriptions for the skills you invoke least are dropped first.
Diagnose:
/doctor
Shows whether the budget is overflowing and which skills are affected.
Tune the budget:
skillListingBudgetFractionsetting — e.g.0.02for 2%SLASH_COMMAND_TOOL_CHAR_BUDGETenv var — fixed char countmaxSkillDescriptionCharssetting — per-entry cap (default 1,536)
Free budget for high-priority skills:
- Set low-priority entries to
"name-only"inskillOverrides(description hidden, slot freed) - Front-load the key use case in each
description(each entry is capped regardless of budget) - Trim
when_to_usetext at the source
Multiple Skills Conflict
Be specific in descriptions. Use distinct trigger terms.
Instead of:
# Skill 1
description: For data analysis
# Skill 2
description: For analyzing data
Use:
# Skill 1
description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.
# Skill 2
description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.
Complete Examples
Example 1: Simple Skill (Single File)
Structure:
commit-helper/
└── SKILL.md
SKILL.md:
---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---
# Generating Commit Messages
## Instructions
1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
- Summary under 50 characters
- Detailed description
- Affected components
## Best practices
- Use present tense
- Explain what and why, not how
Example 2: Skill with Tool Permissions
Structure:
code-reviewer/
└── SKILL.md
SKILL.md:
---
name: code-reviewer
description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
allowed-tools: Read, Grep, Glob
---
# Code Reviewer
## Review checklist
1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage
## Instructions
1. Read the target files using Read tool
2. Search for patterns using Grep
3. Find related files using Glob
4. Provide detailed feedback on code quality
Example 3: Multi-File Skill
Structure:
pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
├── fill_form.py
└── validate.py
SKILL.md:
---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---
# PDF Processing
## Quick start
Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
## Requirements
Packages must be installed in your environment:
```bash
pip install pypdf pdfplumber
```
Example 4: BigQuery Data Analysis Skill
Structure:
bigquery-skill/
├── SKILL.md
└── reference/
├── finance.md
├── sales.md
├── product.md
└── marketing.md
SKILL.md:
---
name: bigquery-data-analysis
description: Query and analyze BigQuery data across finance, sales, product, and marketing datasets. Use when analyzing company metrics, generating reports, or querying BigQuery tables.
---
# BigQuery Data Analysis
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
## Common queries
When the user asks for revenue, always:
1. Filter by `account_type != 'test'`
2. Use UTC timestamps for date filtering
3. Include both MRR and ARR in the results
Checklist for Effective Skills
Before sharing a Skill, verify:
Core Quality
- Description is specific and includes key terms
- Description includes both what the Skill does and when to use it
- Description front-loads the key use case (1,536-char Claude Code cap; 1,024 standard cap)
- SKILL.md body is under 500 lines
- Additional details are in separate files (if needed)
- No time-sensitive information (or in "old patterns" section)
- Consistent terminology throughout
- Examples are concrete, not abstract
- File references are one level deep
- Progressive disclosure used appropriately
- Workflows have clear steps
- Standing instructions written for skill content lifecycle (persists across turns; survives compaction with caveats)
- Uses
${CLAUDE_SKILL_DIR}for any bundled script paths
Code and Scripts
- Scripts solve problems rather than punt to Claude
- Error handling is explicit and helpful
- No "voodoo constants" (all values justified)
- Required packages listed in instructions and verified as available
- Scripts have clear documentation
- No Windows-style paths (all forward slashes)
- Validation/verification steps for critical operations
- Feedback loops included for quality-critical tasks
Testing
- At least three evaluations created
- Tested with Haiku, Sonnet, and Opus (if using multiple models)
- Tested with real usage scenarios
- Team feedback incorporated (if applicable)
Documentation Quality
- Name follows naming conventions (gerund form recommended)
- YAML frontmatter is valid and complete
- Description is written in third person
- File paths use forward slashes
- Longer reference files include table of contents
- MCP tools use fully qualified names (if applicable)
Agent Skills Open Standard (agentskills.io)
Agent Skills is a formal open standard for extending AI agent capabilities with portable, version-controlled skill folders. Originally developed by Anthropic, released openly, and adopted by 35+ tools as of 2026: Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenAI Codex, Goose, Kiro, OpenHands, Letta, Amp, Junie, Databricks Genie Code, Snowflake Cortex Code, Spring AI, Laravel Boost, Factory, OpenCode, Roo Code, TRAE, Mistral Vibe, Workshop, Emdash, Ona, Mux, Autohand Code CLI, Firebender, Piebald, Command Code, fast-agent, nanobot, Google AI Edge Gallery, Qodo, VT Code, pi, Agentman.
Spec home: https://agentskills.io · Source/discussion: https://github.com/agentskills/agentskills
Standard Frontmatter Fields
Per the spec at https://agentskills.io/specification:
| Field | Required | Constraints |
|---|---|---|
name | Yes | 1–64 chars, lowercase a-z + digits + hyphens. No leading/trailing hyphen, no --. Must match parent directory name. |
description | Yes | 1–1024 chars. What it does + when to use it. |
license | No | License name or reference to a bundled license file. |
compatibility | No | Max 500 chars. Intended product, required system packages, network access, etc. |
metadata | No | Arbitrary string→string map for non-spec metadata. |
allowed-tools | No | Space-separated pre-approved tools. Experimental — support varies between agents. |
Claude Code Extensions to the Standard
Claude Code implements a superset. Fields beyond the standard:
when_to_use · argument-hint · arguments · disable-model-invocation · user-invocable · model · effort · context · agent · hooks · paths · shell
Plus settings-level controls: skillOverrides, disableSkillShellExecution, skillListingBudgetFraction, maxSkillDescriptionChars.
Standard Directory Layout
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files
The standard uses
references/(plural); Claude Code's examples often use flat reference files at the skill root. Both work in Claude Code.
Validation
Use the reference library to validate against the standard:
skills-ref validate ./my-skill
Checks frontmatter validity and naming conventions. See https://github.com/agentskills/agentskills/tree/main/skills-ref.
Cross-Tool Portability
A skill written to the standard works in any compatible agent. Tool-specific extensions (Claude Code's context: fork, paths, etc.) are ignored by other agents. Keep portable skills minimal; opt into extensions when you need them.
Resources
Official Documentation
- Agent Skills Open Standard — agentskills.io home
- Agent Skills Specification — formal SKILL.md spec
- Use Skills in Claude Code — canonical Claude Code reference
- Agent Skills Overview (Claude platform)
- Agent Skills Quickstart
- Best Practices Guide
- Use Skills with the Claude API
- Agent Skills in the SDK
GitHub Resources
- agentskills.io Repo & Discussion
- skills-ref Validator
- Agent Skills Cookbook
- Example Skills Repository
Blog Posts
Help Center (Claude.ai)
- What are Skills?
- Using Skills in Claude
- How to create custom Skills
- Teach Claude your way of working using Skills
Quick Reference Commands
# Create personal skill
mkdir -p ~/.claude/skills/my-skill-name
# Create project skill
mkdir -p .claude/skills/my-skill-name
# List personal skills
ls ~/.claude/skills/
# List project skills
ls .claude/skills/
# View skill content
cat ~/.claude/skills/my-skill/SKILL.md
# View a specific skill's frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15
# Check for valid SKILL.md files
ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md
YAML Frontmatter Template
---
name: skill-name # Required by standard; matches dir name
description: What this skill does and when to use it (front-load key use case)
when_to_use: Extra trigger phrases # Claude Code: appended to description
argument-hint: [optional-args-hint] # Shown during autocomplete
arguments: [issue, branch] # Claude Code: named positional args
disable-model-invocation: false # true = only user can invoke
user-invocable: true # false = hidden from / menu
allowed-tools: Read Write Bash # Pre-approved tools (space-separated)
model: inherit # Claude Code: model override or 'inherit'
effort: medium # Claude Code: low|medium|high|xhigh|max
context: fork # Claude Code: run in subagent
agent: Explore # Claude Code: subagent type (with context: fork)
paths: "src/**/*.ts, tests/**/*.ts" # Claude Code: limit auto-activation
shell: bash # Claude Code: bash (default) or powershell
license: MIT # Standard: license name or file
compatibility: Requires git, jq # Standard: env requirements (max 500 chars)
metadata: # Standard: arbitrary string→string map
author: example-org
version: "1.0"
---
Document Created: November 12, 2025 Document Updated: May 11, 2026 Document Version: 4.0 Sources: agentskills.io home + specification, code.claude.com/docs/en/skills, Official Anthropic documentation (overview.md, quickstart.md, best-practices.md), Engineering blog post, GitHub cookbooks
v4.0 changes: agentskills.io open standard now formally documented; new frontmatter fields (when_to_use, arguments, effort, paths, shell); new substitutions ($name, ${CLAUDE_EFFORT}, ${CLAUDE_SKILL_DIR}); skill content lifecycle (persistence + auto-compaction handling); skillOverrides settings; skill listing budget controls; multi-line shell injection; disableSkillShellExecution; Reference vs Task content distinction; expanded bundled skills (/loop, /claude-api, /init//review//security-review via Skill tool); --add-dir skills-only exception; name validation corrected (no consecutive hyphens, must match dir name, no reserved-word rule); description cap clarified (1,536 Claude Code combined vs 1,024 standard).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |