Building Skills

Building Skills

Read [LEARNED.md](LEARNED.md) before building or reviewing any skill.

Core Principles

1. Context Window is Sacred

Skills share context with system prompt, conversation history, other skills, and the user's request. Only add what Claude doesn't already know.

For every line ask: Does this justify its token cost? If Claude knows it, cut it.

2. Progressive Disclosure

Skills load in three stages. Design for this.

| Stage | What loads | Budget | Contains | |-------|-----------|--------|----------| | Discovery | name + description | ~100 tokens | Trigger keywords, when to use | | Activation | SKILL.md body | 100 lines.]

Workflows

[Checklists for multi-step tasks. Conditional routing for different paths.]

Error Reference

[Common errors and fixes. Keep actionable, not exhaustive.]

Self-Learning

[LEARNED.md link + what to record + consolidation rules]

**Stay under 500 lines.** If approaching 300, start splitting to references/.

### 5. Add self-learning

Create LEARNED.md:

```markdown
# skill-name - Learned

## [Category]

- (YYYY-MM-DD) Observation here

Add Self-Learning section to SKILL.md (see [template below](#self-learning-template)).

6. Add scripts with dependency checking

Scripts must detect missing deps and guide setup, not fail silently:

import os, sys
required = ['MY_API_KEY']
missing = [v for v in required if not os.environ.get(v)]
if missing:
    print(f"Missing: {', '.join(missing)}")
    print("Add to ~/.claude/settings.json under \"env\"")
    sys.exit(1)

7. Validate

python3 ~/.claude/skills/building-skills/scripts/validate_skill.py ~/.claude/skills/my-skill

Fix errors, address warnings, re-run until clean.

Restructuring an Existing Skill

1. Audit: SKILL.md line count (500 lines | Split to references/ |

| Nested references (A→B→C) | One level deep from SKILL.md | | No LEARNED.md | Every skill must self-learn | | Unbounded LEARNED.md | Cap 50 lines, consolidate | | README.md, CHANGELOG.md etc | Skills are for AI, not human docs | | "You can use..." in description | Third person: "Processes..." | | Assume deps installed | Check and guide setup on failure | | Large docs in references/ | Put in assets/ if not needed in context |

Self-Learning Template

## Self-Learning

Read [LEARNED.md](LEARNED.md) before using this skill.

**Update LEARNED.md when you discover:** [list skill-specific things to record]

**Consolidation (keep under 50 lines):**
Before adding a new entry, check file length. If over 50 lines:
1. Merge duplicate/overlapping entries into single proven patterns
2. Remove entries older than 3 months that haven't been reinforced
3. Drop one-off observations that never recurred
4. Move detailed context to `LEARNED-archive.md` if worth preserving
5. Keep only entries that would change behavior - if obvious, cut it

Self-Learning

Read [LEARNED.md](LEARNED.md) before building or reviewing any skill.

Update LEARNED.md when you discover:

• Patterns that worked well in production skills
• Description wording that improved or hurt triggering
• Common mistakes when building skills
• Validation gaps (things the validator should catch)
• Structure decisions that helped or hurt

Consolidation (keep under 50 lines): Before adding, check length. If over 50: merge duplicates, prune stale (>3mo unreinforced), drop one-offs, archive to LEARNED-archive.md.

References

• [Patterns Reference](references/patterns.md) - Workflow, output, credential, hook, and testing patterns
• Anthropic Skill Spec - Official skill specification and examples

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: changeflowhq
• Source: changeflowhq/skills
• License: MIT

Install and usage instructions live in the source repository linked above.