changeflowhq/building-skills

Building Skills

Read 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 | <5000 tokens | Instructions, workflows, quick start | | Execution | references/, scripts/ | As needed | Detailed docs, executable code |

Critical: The description field is the trigger mechanism. All "when to use" info goes there, not the body. The body only loads AFTER triggering.

3. Degrees of Freedom

Match instruction specificity to how fragile the task is:

• High freedom (text guidance): Creative tasks, multiple valid approaches. "Write a blog post following these guidelines."
• Medium freedom (parameterized scripts): Preferred pattern exists but adapts. "Run the audit script, interpret results."
• Low freedom (exact scripts, few params): Fragile operations, API calls, deploys. "Run exactly: python scripts/deploy.py --env prod"

4. Self-Learning is Mandatory

Every skill MUST have LEARNED.md with consolidation rules. No exceptions.

Required Structure

skill-name/
├── SKILL.md           # Required. <500 lines. Core instructions.
├── LEARNED.md         # Required. <50 lines. Dated entries + consolidation.
├── scripts/           # Executable code. Runs but never loaded into context.
├── references/        # Detailed docs. Loaded into context on demand (costs tokens).
├── setup/             # Credential templates, setup instructions.
└── assets/            # Files used in output (templates, icons). Never loaded into context.

Key distinction: references/ costs tokens when read. scripts/ and assets/ don't - scripts execute and return output, assets are used in generated files. Put large docs, templates, and data in assets/ not references/.

Frontmatter

---
name: skill-name
description: |
  Third person. WHAT it does + WHEN to use it + trigger keywords.
  This is the primary trigger. Max 1024 chars. No angle brackets.
allowed-tools: Bash Read Write
---

name: kebab-case, max 64 chars, no consecutive/leading/trailing hyphens. Must match directory name.

description: The most important field. Claude reads ALL descriptions to decide which skill to trigger. Front-load trigger conditions. Include keywords users would actually say. Bad: "Manages Google Ads." Good: "Control Google Ads via official API. Create, pause, optimize campaigns, ads, keywords, bids. Run audits. Use when user mentions Google Ads, PPC, AdWords, Quality Score, or ad performance."

allowed-tools: Only tools the skill needs. Common: Bash Read Write Edit.

Allowed keys: name, description, license, allowed-tools, metadata, compatibility. Nothing else.

Creating a New Skill

1. Define trigger examples

Write 3-5 user requests this skill should fire on. These become description keywords and test cases.

2. Scaffold

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

This creates SKILL.md, LEARNED.md, scripts/, references/, setup/, and assets/ with guided TODOs.

3. Write the description FIRST

Before the body. The description determines if the skill ever triggers.

Pattern: [What it does] + [How/via what] + [Specific actions] + [Trigger keywords]

Example: "Local semantic search for markdown knowledge bases using qmd (tobi/qmd). Indexes markdown with BM25 keyword search, vector embeddings, and hybrid reranked queries. Auto-indexes on edits via Claude Code hooks. Use when searching project docs, knowledge bases, meeting notes, or any indexed markdown collection."

4. Write SKILL.md body

# Skill Name

## Quick Start
[Minimal working example - simplest successful use]

## Core Operations
[Brief list. Link to references/ for detail if >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:

# skill-name - Learned

<!-- Keep under 50 lines. Consolidate before adding. -->

## [Category]

- (YYYY-MM-DD) Observation here

Add Self-Learning section to SKILL.md (see template below).

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?), scripts inside skill?, credentials via env vars?, frontmatter valid?, LEARNED.md exists?, description has trigger keywords?
2. Split: Core instructions → SKILL.md. Detailed docs → references/. Code → scripts/. Config → setup/. Output files → assets/.
3. Fix description: Is it the trigger mechanism? Does it front-load keywords? Third person?
4. Add self-learning: LEARNED.md + consolidation section.
5. Validate: Run validate_skill.py.

Patterns

Credentials

~/.claude/settings.json env vars. Never hardcode. Scripts detect and print setup instructions. Document in setup/README.md.

Workflow Checklists

Multi-step tasks get numbered, copy-able checklists with explicit steps.

Conditional Routing

**Creating new?** → See [Creation](#creation)
**Editing?** → See [Editing](#editing)
**Debugging?** → See [references/troubleshooting.md](references/troubleshooting.md)

Feedback Loops

1. Make changes → 2. Run validator → 3. If errors, fix and go to 2

Output Templates

Strict format: provide exact template in assets/. Flexible format: show examples.

Hook Integration

Skills can hook into Claude Code (PreToolUse/PostToolUse) for system-level behavior like auto-indexing or domain blocking. Document in hooks/ subdirectory.

For detailed pattern examples, see references/patterns.md.

Anti-Patterns

| Don't | Do | |-------|-----| | Trigger info only in body | Put trigger keywords in description | | Credentials in skill files | ~/.claude/settings.json env vars | | Scripts in global folder | Scripts inside skill directory | | SKILL.md >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 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 - Workflow, output, credential, hook, and testing patterns
• Anthropic Skill Spec - Official skill specification and examples