# Skill Authoring Guidelines

Principles for creating and modifying skills. Reference this when using the skill-creator or `/forge-evolve`.

## Atomic Single-Responsibility

Each skill does ONE thing. If a skill has two distinct responsibilities, extract one.

**Test:** Can you describe what the skill does in one sentence without "and"? If not, it's compound.

| Atomic | Compound (split it) |
|--------|-------------------|
| "Enforce TDD discipline" | "Enforce TDD discipline AND decide execution routing" |
| "Review code quality" | "Review code quality AND manage PR creation" |
| "Debug systematically" | "Debug systematically AND fix the bug" |

## Do Not Duplicate Rules

Rules in `rules/common/` are always loaded. Skills should not restate them.

| If this exists in a rule... | The skill should... |
|---|---|
| Testing standards (`testing.md`) | Reference, not repeat. Keep only TDD-specific deltas. |
| Verification protocol (`verification.md`) | Not re-explain "verify before writing code." |
| Coding standards (`coding-standards.md`) | Not re-explain "minimal code" or "no over-engineering." |

**Why:** Duplication drifts. When the rule is updated, the skill copy becomes stale and may contradict it.

## Target Size

| Size | Assessment |
|------|-----------|
| < 100 lines | Likely too thin — missing process constraints |
| 100-250 lines | Ideal for most skills |
| 250-400 lines | Acceptable for complex skills (architecture, task decompose) |
| > 400 lines | Review for bloat — likely duplicates rules or has compound responsibility |

## Avoid Internal Repetition

State each rule once. Do not restate it in:
- The overview AND the process AND the checklist AND the red flags AND the examples AND the final rule

Choose the highest-signal location. One clear statement beats six diluted ones.

## Separate Methodology from Orchestration

Skills define HOW to do something (methodology). Orchestration decisions (which agent to dispatch, how to read manifest state, whether to fork or inline) should be minimal — a short section at most, not a parallel responsibility.

**Methodology:** RED-GREEN-REFACTOR cycle, review criteria, debugging phases.

**Orchestration:** Dispatch builder agent with task + artifacts only, read execution.mode from manifest, merge worktrees. Keep this to a routing table, not a protocol.

## Where Workflow Goes: Command vs Skill (v6 convention)

Forge places multi-phase workflows in **commands**, not skills. This is an intentional divergence from the Anthropic Skills convention (which puts multi-step workflows in skills with auto-load on context match).

**v6 rule:**

| Content type | Goes in |
|---|---|
| Phase orchestration across an SDLC pipeline (concept → wireframe → prototype → iterate → codify → production-build → deliver) | Command (`commands/feature.md`, `commands/greenfield.md`, etc.) |
| Per-phase or per-operation methodology, with its own dispatch logic | Skill (`skills/harden/SKILL.md`, `skills/build-tdd/SKILL.md`, etc.) |
| Specialized role definitions invoked with their own context window | Agent (`agents/*.md`) |
| Ad-hoc / one-shot / mid-task corrections | Command (Claude Code's native pattern — `/btw`, `/simplify`, etc.) |
| Auto-load on user intent description ("add a logger here") | Rule + state-aware routing (`rules/common/skill-selection.md`) |

**When tempted to put a multi-step workflow in a skill:** ask whether it needs human-, script-, or CI-readable graph state. If yes (gate-enforcer reads the manifest, telemetry tracks invocations), keep it in a command. If no (pure prose orchestration; no external readers), a skill works.

**Why this matters at authoring time:** an inadvertently-skill-shaped workflow with multi-phase orchestration creates a parallel state model alongside commands+manifests. Two sources of truth for "what phase are we in" is the failure mode to avoid.

**v7 plan:** Revisit. Anthropic's hybrid pattern (`/feature` command becomes a thin invocation of `feature-workflow` skill) is the long-term direction. Until then, treat the command/skill boundary as documented above. See `AGENTS.md` "Architectural Layers" section.

## Agent/Skill Boundary

Agents and skills are different layers:
- Skills are for human or inline sessions. They can decide when to dispatch an agent.
- Agents do not load skills via frontmatter. The agent definition must contain its own execution methodology inline.
- Dispatch prompts should pass task scope and required artifacts only, not a copy of the parent skill text.

## Agent Dispatch Ownership

Skills that dispatch agents should:
- Name the agent and the condition for dispatch
- Keep the dispatch handoff to task scope plus required artifacts
- Not duplicate the agent's own protocol (the agent definition handles that)
- Use a guard only when the skill itself should be skipped in a given context; do not rely on skill-preloading recursion guards

## I/O Contract

Use an I/O Contract when the skill's artifact handoffs, downstream consumers, or manifest updates need to be explicit in the workflow graph. Pure methodology skills can omit the table when it only duplicates surrounding orchestration.

| Field | Required | Purpose |
|---|---|---|
| Requires | Usually | What artifacts must exist before this skill runs |
| Produces | Usually | What artifacts this skill creates |
| Feeds into | Usually | Which skills consume this skill's output |
| Updates manifest | If applicable | Which manifest fields change |
| Dispatches | If applicable | Which agents this skill dispatches |

## Description Authoring

The `description` field in frontmatter drives Claude Code's auto-triggering — it decides whether to load the full SKILL.md. Get this right.

**Format:** Single "Use when..." sentence. No "and" joining two responsibilities. Command-agnostic — never reference `/feature`, `/hotfix`, or other command names.

**Target:** 15-25 words, under 250 characters. Front-load keywords — truncated text still aids discovery.

**What belongs here:** When to use it (triggering conditions) and what it does (one capability).

**What belongs in the body:** Detailed triggering scenarios, skip conditions, command-specific scoping, and methodology. Use a `## When to Use` section in the SKILL.md body for this (see `support-skill-validator` for an example).

**Why this split:** Claude Code uses semantic matching on descriptions to decide relevance. Long descriptions dilute signal — the matcher weighs every word. Detailed skip/scope logic is needed by the agent *after* the skill is loaded, not before.

| Good | Bad (don't do this) |
|------|---------------------|
| `"Use when encountering any bug, test failure, or unexpected behavior — enforces systematic root cause investigation."` | `"TRIGGER when: any bug, test failure, error; user says 'it's broken', 'not working'. Enforces root cause investigation, fact-checking, and the 3-fix threshold. SKIP for: cosmetic tweaks, /hotfix emergency path."` |
| `"Use when code has been written — orchestrates the review chain (safety → craft → reachability → gotcha-hunter → Codex adversarial) with risk-based escalation."` | `"Use after build-tdd completes, per-task during /feature build phase, or as final review before PR. Multi-pass chain. Scope varies: critical-pass only for /hotfix, per-task + final for /feature and /refactor."` |

**Standalone vs chained skills:** Most skills are invoked by commands in sequence. Their descriptions must signal *which step they are*, not *what the user's goal is* — otherwise broad intent ("I want to build X") triggers multiple skills simultaneously instead of routing to a command.

| Skill type | Description pattern | Example |
|---|---|---|
| **Standalone** (user may invoke directly) | "Use when {triggering condition}" | `"Use when encountering any bug, test failure, or unexpected behavior..."` |
| **Chained** (always inside a command sequence) | "Use {phase signal} to {specific step}" | `"Use during the build phase to write or change production code..."` |

Phase signals that prevent false triggers on broad intent: "Use after architecture is approved...", "Use as the first planning step...", "Use during the build phase...", "Use when an approach has been approved...". These imply a prior step completed, so they won't fire on "I want to build a task manager."

**Cross-harness reference:**

| Harness | Pattern | Lesson for forge |
|---------|---------|-----------------|
| SuperPowers (obra) | `"Use when..."` + symptoms, ~200 chars | Concrete triggers, no workflow details — forge's primary lineage |
| Claude Code official | `"Use when..."` + keywords, ~250 chars | Semantic matching; front-load keywords, third person |
| Everything Claude Code (AffaanMustafa) | Brief frontmatter + `## When to Activate` in body | Split concerns — forge adopts this with `## When to Use` |
| gStack (garrytan) | 200-300 word descriptions with voice aliases | Over-specified; command-coupled; descriptions became stale — the anti-pattern |

## Checklist for New Skills

- [ ] One sentence description — "Use when..." format, no "and", under 250 chars, command-agnostic
- [ ] No content duplicated from `rules/common/`
- [ ] Under 400 lines
- [ ] Each rule stated once, in one location
- [ ] Orchestration is a short section, not a parallel responsibility
- [ ] Agent dispatch passes task scope + artifacts only; agent owns its methodology inline
- [ ] Add an I/O Contract only when it materially clarifies artifact handoffs or manifest updates
- [ ] Run `/validate` after adding

## Checklist for Modifying Skills

- [ ] Cross-check with rules — did the rule already cover what you're adding?
- [ ] Check line count before and after — did it grow significantly?
- [ ] Review for internal repetition — did you add a point already made elsewhere in the file?
- [ ] If adding agent dispatch — is the handoff limited to task scope + artifacts, with methodology kept in the agent?
- [ ] Run `/validate` after modifying