aspiers/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

---
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:

• Anthropic Skill Authoring Best Practices
• Skills Overview
• Progressive Disclosure Architecture