# Skill Authoring

> Create and validate Claude Code Skills. Use when building new skills, improving existing skills, or discussing skill architecture, frontmatter, progressive disclosure, or best practices.

- Skill: `diegosouzapw/skill-authoring-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/skill-authoring-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/skill-authoring-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/diegosouzapw/skill-authoring-3

---


# Skill Authoring

Build effective Skills that Claude can discover and use.

## Quick Start

```bash
# Initialize a new skill
python .claude/skills/skill-authoring/scripts/init_skill.py my-skill-name

# Validate a skill
python .claude/skills/skill-authoring/scripts/quick_validate.py .claude/skills/my-skill/

# Package for distribution
python .claude/skills/skill-authoring/scripts/package_skill.py .claude/skills/my-skill/
```

## Skill Structure

```
my-skill/
├── SKILL.md              # Required: instructions + YAML frontmatter
├── scripts/              # Optional: executable code (not loaded into context)
├── references/           # Optional: documentation (loaded when needed)
└── assets/               # Optional: output templates, images
```

## YAML Frontmatter

```yaml
---
name: my-skill-name
description: Does X for Y. Use when working with Y or when user mentions X.
---
```

**Rules:**
- `name`: lowercase, hyphens, max 64 chars, no "anthropic"/"claude"
- `description`: max 1024 chars, third person, include WHAT + WHEN triggers

## Three-Level Loading

| Level | When | Cost | Content |
|-------|------|------|---------|
| L1: Metadata | Startup | ~100 tokens | name + description |
| L2: Instructions | Triggered | <5k tokens | SKILL.md body |
| L3: Resources | As needed | Unlimited | scripts/, references/ |

## Core Principles

### 1. Be Concise

Claude is smart. Only add what Claude doesn't know.

```python
# BAD: 150 tokens explaining what PDFs are
# GOOD: 50 tokens with just the code
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

### 2. Match Freedom to Fragility

| Task Type | Freedom | Approach |
|-----------|---------|----------|
| Multiple valid ways | High | Text guidelines |
| Preferred pattern | Medium | Pseudocode/templates |
| Fragile operations | Low | Exact scripts |

### 3. Progressive Disclosure

Keep SKILL.md < 500 lines. Split details into references/:

```markdown
## Quick start
[Core instructions]

## Advanced
See [references/advanced.md](references/advanced.md)
```

### 4. One-Level Deep References

```markdown
# GOOD: flat
SKILL.md -> references/api.md
SKILL.md -> references/examples.md

# BAD: nested
SKILL.md -> advanced.md -> details.md -> info
```

## Output Patterns

See [references/output-patterns.md](references/output-patterns.md) for:
- Template Pattern (strict vs flexible)
- Examples Pattern (input/output pairs)

## Workflow Patterns

See [references/workflows.md](references/workflows.md) for:
- Sequential workflows
- Conditional workflows
- Feedback loops

## Scripts

**Execute, don't load:**
```markdown
Run: `python scripts/analyze.py input.pdf`
```

**Handle errors explicitly:**
```python
def process(path):
    try:
        return open(path).read()
    except FileNotFoundError:
        print(f"Creating {path}")
        return ""
```

## Anti-Patterns

| Avoid | Fix |
|-------|-----|
| Windows paths `\` | Use `/` always |
| Too many options | Provide sensible default |
| Magic numbers | Document constants |
| Deep nesting | Keep refs 1 level deep |
| First person description | Use third person |

## Validation Checklist

- [ ] name: lowercase, hyphens, max 64 chars
- [ ] description: WHAT + WHEN, third person
- [ ] SKILL.md < 500 lines
- [ ] References 1 level deep
- [ ] Scripts handle errors
- [ ] No Windows paths