review-flow: Skill for Claude Code

Skill Creator

Guide for creating effective skills in the ReviewFlow project.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities with specialized workflows, domain knowledge, and tool integrations. They transform Claude from a general-purpose agent into a project-specialized one.

What Skills Provide

1. Specialized workflows — Multi-step procedures (e.g. /ship, /tdd, /implement-feature)
2. Domain expertise — ReviewFlow-specific knowledge, architecture patterns, business rules
3. Bundled resources — References and assets loaded on demand

Core Principles

Concise is Key

The context window is a shared resource. Only add context Claude does not already have. Challenge each paragraph: "Does Claude really need this?" If not, remove it.

Set Appropriate Degrees of Freedom

• High freedom (text instructions): multiple approaches valid, context-dependent
• Medium freedom (pseudocode/templates): preferred pattern exists, variation acceptable
• Low freedom (shell scripts): operations are fragile, consistency critical

Anatomy of a ReviewFlow Skill

.claude/skills/<skill-name>/
├── SKILL.md            (required)
│   ├── YAML frontmatter (required: name + description)
│   └── Markdown instructions
└── references/         (optional — bundled docs loaded by reference)

Skill Creation Process

1. Understand the skill with 2-3 concrete usage examples
2. Draft the frontmatter (name, description, user-invocable)
3. Write the body — imperative instructions, low prose
4. Test it: invoke /skill-name and verify Claude follows the workflow
5. Register in CLAUDE.md skills table

Frontmatter Reference

---
name: skill-name            # kebab-case, matches folder name
description: >              # PRIMARY TRIGGER — LLM reads only this initially.
  One or two sentences.     # Include natural-language trigger phrases.
  "Use when the user says X, Y, Z."
user-invocable: true        # true = can be invoked with /skill-name
allowed-tools: Bash, Read   # optional — restrict available tools
---