Skip to content

README.md

Latest commit

 

History

History
189 lines (148 loc) · 6.36 KB

README.md

File metadata and controls

189 lines (148 loc) · 6.36 KB

Skills

You don't need to memorize slash commands. Just describe what you want naturally.

How It Works

Skills use the native Claude Code SKILL.md format. Claude sees skill descriptions in its context and automatically invokes them based on your conversation.

You: "Fix the auth bug"

Claude automatically:
1. Recognizes this matches the "fix" skill
2. Forks context (keeps main conversation clean)
3. Spawns explore agent → investigate
4. Spawns tester agent → reproduce
5. Spawns implementer agent → fix
6. Returns clean summary

Natural Language Examples

What You Say Skill Auto-Invoked What Happens
"Fix the broken login" fix explore → tester → implementer → review
"Build a user dashboard" build planner → scaffolder → implementer → test
"How does auth work?" explore Codebase investigation, returns summary
"Review my changes" review Code review against Darkroom standards
"Create a Button component" component Scaffolds component with CSS module
"What could go wrong?" premortem Risk analysis before implementing
"Double check this is correct" verify finder → adversary → referee
"Clean up our rules" consolidate Audit and merge rules/skills/learnings
"Done for today" create-handoff Saves session state

Skill Categories

Workflows (Multi-Agent Delegation)

These fork context and delegate to specialized agents:

Skill Triggers On Agents Used
fix bug, broken, error, not working explore → tester → implementer
build build, create, implement, add feature planner → scaffolder → implementer
refactor refactor, clean up, reorganize explore → implementer → reviewer
review review, check, PR, changes reviewer
test test, write tests, coverage tester
orchestrate complex task, coordinate maestro
ship ship it, create PR, /pr, /ship tester → reviewer → implementer
f-thread compare approaches, architecture decision parallel oracles → scoring matrix
l-thread overnight, long running, autonomous task phased execution with checkpoints
verify verify, double check, prove it, adversarial, audit finder → adversary → referee

Creation (Direct Output)

These create files directly in main context:

Skill Triggers On
component create component, new component
design-tokens design tokens, type scale, color palette, spacing system, theme setup
hook create hook, custom hook
init new project, initialize, setup

Research (Forked Context)

These fork context for clean exploration:

Skill Triggers On
explore how does, where is, find, understand
docs documentation, how to use, library API
ask advice, guidance, what should I
tldr who calls, dependencies, semantic search
premortem risks, what could go wrong
discovery requirements, scope, figure out
prd PRD, requirements document, product spec
project project status, update the issue, sync with github, show my tasks

Tools

Skill Triggers On
debug screenshot, visual bug, inspect element
figma figma, compare to design, design fidelity, extract tokens from figma
qa visual check, accessibility, validate
lenis smooth scroll, lenis setup

Utility

Skill Triggers On
audit /audit — analyzes Claude's Bash command log (categories, security, repeats)
teams parallel agents, split work, fan out
consolidate clean up rules, simplify config, contradictions, spa day, prune

Session Management

Skill Triggers On
learn AUTO: after non-obvious fix, pattern, gotcha
context context window, running out of context
checkpoint save state, save progress, checkpoint
create-handoff done for today, save state
resume-handoff resume, continue, last session

The learn Skill (Auto-Applied)

Claude automatically stores learnings when it should remember something.

Auto-triggers when:

  • Fixing a non-obvious bug
  • Discovering a useful pattern
  • Encountering a gotcha or edge case
  • Finding a tool/library feature
  • Making an architecture decision

Learnings persist across sessions and are recalled on session start.

Skill Structure

Each skill is a directory with SKILL.md:

skills/
├── fix/
│   └── SKILL.md
├── explore/
│   └── SKILL.md
├── learn/
│   └── SKILL.md
└── ...

SKILL.md Format

---
name: skill-name
description: |
  What this skill does. Use when:
  - User says "X", "Y", "Z"
  - Specific situations that trigger this skill
context: fork          # Run in isolated context
agent: agentName       # Which agent runs it
allowed-tools: [...]   # Restrict available tools
---

# Skill Instructions

[What Claude does when skill is invoked]

Key Options

Option Effect
description Tells Claude WHEN to auto-invoke (critical!)
context: fork Runs isolated, returns summary to main
agent: X Uses specific agent (explore, reviewer, etc.)
allowed-tools Restricts which tools can be used

Adding Custom Skills

  1. Create directory: skills/my-skill/
  2. Create SKILL.md with frontmatter
  3. Write intent-based description (what triggers it?)
  4. Restart Claude Code to load

Context Thresholds

Context % Warning Action
70-79% Notice Save checkpoint, consider handoff
80-89% Warning Save checkpoint + commit work, create handoff soon
90%+ Critical Save checkpoint, create-handoff auto-suggested

Checkpoints (/checkpoint save) are lightweight task snapshots. Handoffs (/create-handoff) are full session transfers. Use both at thresholds.

Legacy

The old skill-rules.json and commands/*.md formats have been replaced by */SKILL.md files. Skills are now the unified way to extend Claude's capabilities.

Debugging

# Check which skills Claude sees
/skills

# Manually invoke a skill
/darkroom:fix "the auth bug"

# Check learnings
bun ~/.claude/src/scripts/learning.ts recall all