Using Skills

Skill Selection Rules

Single-Skill Tasks (default)

Most tasks need exactly one skill. Pick it and go.

User asks: "Fix the login timeout bug"
→ implementing-features (clear bug fix with acceptance criteria)

Multi-Skill Composition

Compose only when one skill's output feeds another skill's input.

User asks: "Design and implement a caching layer"
→ designing-systems (produces ADR with approach)
→ implementing-features (uses ADR as spec)
→ writing-tests (validates implementation)

When Not to Use a Skill

• Trivial questions — answer directly
• File reads or searches — use tools directly
• Conversation or clarification — talk to the user
• Already in-progress — don't re-invoke a skill you're currently executing

Skill Invocation Protocol

When invoking a skill:

1. Read the SKILL.md — every time. Don't rely on cached knowledge.
2. Check pre-flight conditions — most skills list what must be true before starting
3. Follow the execution steps — in order, skipping only steps marked optional
4. Produce the specified output — in the format the skill defines
5. Self-verify — check the skill's constraints before declaring done

Invocation Template

I'm using the [skill-name] skill to handle this task.

Pre-flight:
- [x] Condition 1 met
- [x] Condition 2 met

Proceeding with execution steps...

Composition Patterns

Sequential Chain

Skills execute one after another, each consuming the previous output.

planning-tasks → implementing-features → writing-tests

Rule: Only chain when output A is input B. Independent tasks run separately.

Research Fork

When planning reveals unknowns, fork into research before continuing.

planning-tasks
  ├── researching-options (unknown 1)
  ├── researching-options (unknown 2)
  └── continue with implementing-features

Design Gate

When implementation requires an architecture decision, gate on design.

designing-systems (must complete first)
  └── implementing-features (uses ADR as spec)

Skill Categories

Infrastructure Skills

Setup and context management. Typically run once or periodically.

• initialize-repo — set up .context/ for a new project
• context-loader — how to read .context/ efficiently
• context-maintenance — keep .context/ accurate
• context-review — full codebase scan to sync docs

Planning & Design Skills

Define what to build and how. Run before implementation.

• planning-tasks — break goals into task lists
• task-plan — canonical plan format for handoffs
• designing-systems — architecture decisions (ADRs)
• design-first — triage: design first or implement directly?
• researching-options — evaluate libraries/approaches

Implementation Skills

Build and validate. The core work loop.

• implementing-features — write/modify code
• writing-tests — write/run tests
• systematic-debugging — structured debugging process

Discipline Skills

Cross-cutting quality practices. Referenced during other skills.

• common-constraints — universal agent rules
• verification-checklist — pre-completion checklist
• testing-discipline — TDD and test quality practices
• commit-discipline — git commit conventions

Process Skills

Reflection and improvement. Run after tasks complete.

• task-retrospective — structured reflection
• knowledge-graduation — promote patterns to permanent docs

Constraints

• Always read a skill's SKILL.md before invoking it — never work from memory
• Don't compose more than 4 skills in a single workflow without user confirmation
• If no skill matches the task, proceed without one — don't force-fit
• Follow skills/_shared/conventions.md for all cross-cutting behaviors
• When a skill says "stop and check in with the user," do it — don't skip checkpoints