skill-authoring

# 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

```yaml
---
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](references/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:

```python
# 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:
- [Anthropic Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Progressive Disclosure Architecture](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work)