Skip to content

SKILLS.md

Latest commit

 

History

History
213 lines (164 loc) · 5.75 KB

SKILLS.md

File metadata and controls

213 lines (164 loc) · 5.75 KB
Raw

Skills Architecture

Skills are persistent knowledge bases that survive session compaction and provide project-specific context to Claude.

What Are Skills?

Unlike commands (one-time instructions), skills are persistent domain knowledge that Claude loads based on context. They enable:

  • Zero context loss between sessions
  • Project-specific expertise without re-explaining
  • Consistent decision-making across time
  • Accumulated tribal knowledge

Skill vs Command

Aspect Command Skill
Purpose Execute a task Provide knowledge
Lifespan Single invocation Persistent
Structure Single markdown file Directory with files
Loading Explicit (/command) Automatic by context
Updates Overwrite Governed updates

Skill Structure

.claude/skills/[skill-name]/
├── SKILL.md                    # Entry point (~400 lines max)
├── Reference/
│   ├── skill-maintenance.md    # Update governance (REQUIRED)
│   ├── implementation-status.md # Current state (REQUIRED)
│   └── [topic].md              # Domain-specific files
└── Templates/                  # Optional
    └── [entity]-template.md    # For tracking entities

SKILL.md

The main entry point. Must contain:

  1. YAML frontmatter - Name and trigger description
  2. Mandatory update gate - Instructions to read maintenance first
  3. Quick reference - Project overview tables
  4. Reference file index - What's in each file
  5. Critical rules - Non-negotiable principles
  6. Changelog - Update history

Reference/skill-maintenance.md

Governance for skill updates. Required sections:

  1. Update trigger protocol
  2. Pre-update checklist
  3. Update classifications (NEW, UPDATE, DUPLICATE, CORRECTION)
  4. Domain-specific procedures
  5. Post-update verification
  6. Cross-file synchronization rules
  7. Emergency procedures

Creating Skills

Using /create-skill

/create-skill

The skill generator will:

  1. Analyze your conversation history
  2. Identify knowledge categories
  3. Propose a structure
  4. Request confirmation
  5. Generate all files

Manual Creation

Copy templates from ~/.claude/skills/skill-generator/Templates/:

  • project-skill-template.md → SKILL.md
  • maintenance-template.md → Reference/skill-maintenance.md

Updating Skills

Using /update-skill

/update-skill

The process:

  1. Reads existing skill-maintenance.md
  2. Identifies what's new in conversation
  3. Classifies each update
  4. Applies changes with markers
  5. Updates changelogs

Update Classifications

Classification When Action
NEW Topic doesn't exist Append to section
UPDATE Info has changed Mark old [SUPERSEDED], add new
DUPLICATE Already present Skip
CORRECTION Info was wrong Mark old [CORRECTED], add fix

Status Flags

Entity/Project Status

[ACTIVE]      - Currently in progress
[COMPLETED]   - Finished
[CLOSED]      - Fully concluded
[PAUSED]      - On hold
[CANCELLED]   - No longer happening

Technical Status

[BUILT]       - Implemented and deployed
[PENDING]     - Scoped, not built
[PLANNED]     - Discussed, not scoped

Marker Flags

[SUPERSEDED: YYYY-MM-DD]    - Replaced by newer info
[CORRECTED: YYYY-MM-DD]     - Was incorrect, fixed
[UNCONFIRMED]               - Not yet verified
[ASSUMPTION]                - Based on inference
[NEEDS CLARIFICATION]       - Gap requiring input

Best Practices

DO

  • Keep SKILL.md under 400 lines
  • Use tables over prose
  • Include specific values (dates, numbers)
  • Document the "why" not just the "what"
  • Mark uncertainty explicitly
  • Update changelogs religiously

DON'T

  • Fragment into multiple skills per project
  • Delete information (use SUPERSEDED)
  • Write narrative prose
  • Leave empty required sections
  • Update without reading maintenance doc
  • Skip the verification checklist

The Skill Generator

The skill-generator meta-skill teaches Claude how to create skills. It includes:

~/.claude/skills/skill-generator/
├── SKILL.md                         # Main instructions
├── Reference/
│   ├── skill-maintenance.md         # Self-governance
│   ├── phase-procedures.md          # 6-phase creation process
│   └── formatting-standards.md      # Formatting rules
└── Templates/
    ├── project-skill-template.md    # SKILL.md template
    ├── maintenance-template.md      # skill-maintenance template
    └── entity-template.md           # Entity file template

Example Skill

---
name: mortgage-coach
description: Knowledge base for the Mortgage Coach web application.
  Use when working in mortgage-coach/ directory or discussing TCA
  reports, loan calculations, or mortgage-related features.
---

# Mandatory: Read Before ANY Updates

**If you are about to modify ANY file in this skill:**
1. **STOP** — Read `Reference/skill-maintenance.md` first
[...]

# Mortgage Coach Knowledge Base

## Quick Reference

| Field | Value |
|-------|-------|
| **Project** | Mortgage Coach Clone |
| **Type** | Next.js Web Application |
| **Status** | [ACTIVE] |
| **Directory** | `mortgage-coach/` |

## Module Status

| Module | Status |
|--------|--------|
| Authentication | ⏳ PENDING |
| Presentation Builder | ⚠️ PARTIAL |
| Calculations Engine | ✅ BUILT |
| TCA Report | ⚠️ PARTIAL |

[...]

Skill Discovery

Claude automatically discovers relevant skills by:

  1. Checking current working directory
  2. Matching skill descriptions to context
  3. Loading appropriate Reference/ files as needed

Skills are NOT loaded in full—Claude loads SKILL.md first, then specific Reference files based on the task at hand.