Skill Authoring

Create effective Claude Code skills that follow Anthropic's official best practices and guidelines.

When to Use This Skill

Use this skill when:

Creating new skills from scratch
Refactoring existing skills for better structure
Ensuring skills follow Anthropic guidelines
Troubleshooting skill discovery or performance issues
Optimizing skills for token efficiency

Core Principles

1. Concise is Key

Context window is shared - be economical with tokens
Assume Claude is already smart - don't over-explain basics
Challenge every piece of information: "Does this justify its token cost?"

2. Progressive Disclosure

Skills load in three tiers:

Level 1: Metadata (name/description) - always loaded (~100 tokens/skill)
Level 2: SKILL.md body - loaded when triggered (<500 lines recommended)
Level 3: Reference files/scripts - loaded/executed as needed

3. Appropriate Freedom Levels

High freedom: Text instructions for flexible, context-dependent tasks
Medium freedom: Parameterized scripts with some variation
Low freedom: Specific scripts for fragile, error-prone operations

Skill Structure

Required Files

Each skill is a directory containing a SKILL.md file. Multiple locations are scanned, in order of preference:

Project-local (walked up from cwd to git worktree root):

.agents/skills/<name>/SKILL.md — preferred cross-platform standard
.claude/skills/<name>/SKILL.md — Claude-compatible
.opencode/skills/<name>/SKILL.md — OpenCode-specific

Global (user home):

~/.agents/skills/<name>/SKILL.md
~/.claude/skills/<name>/SKILL.md
~/.config/opencode/skills/<name>/SKILL.md

Use .agents/skills/ for new skills — it is the emerging cross-platform standard supported by Claude Code, OpenCode, and other agents.

.agents/skills/skill-name/
├── SKILL.md (required - instructions + metadata)
└── Optional bundled resources:
    ├── scripts/     - Executable code (Python/Bash/etc.)
    ├── references/  - Documentation loaded as needed
    └── assets/      - Files for output (templates, images)

YAML Frontmatter Requirements

---
name: skill-name-here          # lowercase, hyphens, max 64 chars
description: What + When       # max 1024 chars, include trigger contexts
---

Critical: Description must include both WHAT the skill does AND WHEN to use it. Include:

Task types (create, analyze, process)
File types (.pdf, .docx, .json)
Keywords users might mention
Specific trigger contexts

Example `SKILL.md`

N.B. The following example is indented here so that triple backticks can be included within the example, but when creating / editing a SKILL.md, most of it should not be indented.

Note also that SKILL.md files do not necessarily need to provide and use helper tools; however it's included this example skill for illustrative purposes.

---
name: example-skill
description: Process example files with specific formatting. Use when users mention examples, processing, or .example files.
---

# Example Skill

Process example files following consistent patterns.

## When to Use This Skill

- When processing .example files
- When users ask about example formatting
- When converting example formats

## How It Works

1. Read the input file using the example-parser tool
2. Apply formatting rules from references/rules.md
3. Write output to destination

## Usage

```bash
python scripts/process_example.py input.example output.txt
```

## How to use the example-parser tool

```python
from example_parser import parse

result = parse("data.example")
print(result.summary)
```

## Reference Files

- [Formatting Rules](references/rules.md)
- [Parser Documentation](references/parser.md)

Best Practices

Naming Conventions

Use gerunds or gerundial nouns:

Gerunds (verb + -ing): processing-pdfs, analyzing-spreadsheets, managing-databases
Gerundial nouns (verb-derived nouns): generation, authoring, initialization, management
✅ processing-pdfs, generating-prps, authoring-skills
❌ pdf-helper, data-utils, skill-creator

Writing Effective Descriptions

Write in third person (not "I can help" but "Processes files")
Include specific triggers: "Use when working with PDF files or when users mention PDFs, forms, or document extraction"
Be specific about capabilities and contexts

Progressive Disclosure Patterns

High-Level Guide with References

# PDF Processing

## Quick start

Extract text with pdfplumber:

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

Common Anti-Patterns to Avoid

Over-Verbose Instructions

❌ Paragraphs explaining basic concepts Claude knows
✅ Concise examples that demonstrate patterns

Deep Reference Nesting

❌ SKILL.md → file1.md → file2.md → file3.md
✅ SKILL.md → file1.md, file2.md, file3.md (one level deep)

Time-Sensitive Content

❌ "Current best practice as of 2025"
✅ "Current best practice (see UPDATES.md)"

Windows Path Usage

❌ scripts\helper.py
✅ scripts/helper.py

Executable Scripts Best Practices

Solve Problems, Don't Punt

Handle errors explicitly rather than letting Claude figure it out:

# Good: Handle file not found

def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"File {path} not found, creating default")
        with open(path, 'w') as f:
            f.write('')
        return ''

Provide Utility Scripts

Pre-made scripts offer advantages:

More reliable than generated code
Save tokens (no need to load contents)
Ensure consistency across uses

References

For complete official guidelines, see:

skill-authoring