coding-guidelines.md

Coding Guidelines

These guidelines apply to writing and modifying SKILL.md files.

Skill Structure

Every skill follows the same section order:

1. YAML frontmatter (--- delimited)
2. Title (# <Action Verb> <Object>)
3. Description paragraph (optional — omit if the title is self-explanatory)
4. ## Input — document $ARGUMENTS, default behavior, and, for skills with structured primary input, the shared trailing context syntax (-- <additional context>)
5. ## Process — numbered ### Step N: <Action> sections
6. ## Output Format (optional) — template for structured output
7. ## Guidelines — brief behavioral rules as a list
8. ## Related Skills — link to the next relevant skill in the workflow
9. ## Example Usage — slash command examples

Frontmatter Conventions

• name: kebab-case, prefixed with forge- (e.g., forge-setup-project)
• description: one sentence describing what the skill does and when to use it. This text is what compatible agents use for skill discovery, so it must be descriptive.
• disable-model-invocation: set to true for skills that should only be invoked by the user via slash command (workflow entry points). Omit or set to false for skills that agents may auto-activate.
• allowed-tools: comma-separated list of tools the skill may use. Omit to allow all tools.

Writing Process Steps

• Each step should be a single, focused action
• Include bash examples for any CLI operations (especially gh and git commands)
• Use AskUserQuestion for user decisions — never assume
• Steps should be numbered sequentially and named with action verbs: "Create", "Fetch", "Analyze", "Generate"

Writing Delegate Steps

When a skill benefits from fresh context (e.g., unbiased review), use two complementary mechanisms:

1. context: fork frontmatter — Claude Code's native mechanism. Forks the entire skill into a sub-agent. Ignored by runtimes that don't support it.
2. (delegate) step annotation — cross-runtime fallback. Instructs any runtime with sub-agent support to delegate a specific step.

Both can coexist in the same skill — context: fork handles Claude Code, (delegate) hints to other runtimes.

Writing (delegate) steps:

• Mark the step title: ### Step N: <Action> (delegate) — or #### <Action> (delegate) when delegation is a conditional sub-step within a larger step
• Open with the delegation instruction and inline fallback
• Sub-agent instructions are either fully self-contained in a blockquote or composed from a role reference plus task-specific instructions (see Using Roles in Delegate Steps below)
• List Inputs provided to sub-agent — data the parent must pass (diff output, file contents, project conventions)
• List Expected output — what the parent receives back
• Only delegate when it provides a genuine quality improvement — fresh context for unbiased review (e.g., reflect) or parallel sub-agents for divergent exploration (e.g., the optional approach-exploration step in shape)

Using Roles in Delegate Steps

When a delegation step benefits from a separated persona, extract it into a role file under the skill's roles/ directory (see Architecture — Role File Format). The skill then references the role and provides only task-specific instructions:

#### Research (delegate)

Delegate to a [forge-scout](roles/forge-scout.md) sub-agent that receives only
the questions. If the runtime does not support sub-agents, read the role
file and answer each question following its rules.

**Inputs provided to sub-agent:**
- Role: [forge-scout](roles/forge-scout.md)
- The research questions

**Expected output:** One factual answer per question.

The role file defines the persona, behavior rules, and output format. The skill's blockquote provides only the task-specific checklist or instructions. Runtimes that support role-aware delegation compose both into the sub-agent's context; runtimes that don't can read the role file inline.

Important: role files are not the same thing as runtime agent definitions. Do not assume a role file's name: can be passed as agent: "<name>" to a sub-agent tool. If the runtime separates prompt content from agent selection, push the role file body via the delegated task or systemPrompt. If selecting an agent also selects a model/provider, prefer leaving the agent unspecified so the sub-agent inherits the parent session configuration unless the user has explicitly configured a matching agent. Runtime-specific agent files, presets, or harness config are optional tuning layers — Forge must still work correctly without them.

Role files live inside the skill directory when only one skill uses them. When multiple skills need the same role or reference, the file lives in skills/_shared/ (or skills/_shared/roles/ for roles) — the shared layer avoids duplication drift while keeping dependencies explicit.

Role File Format

Role files define reusable sub-agent personas. Skill-specific roles live under the skill's roles/ directory; cross-skill roles live in _shared/roles/.

YAML Frontmatter:

---
name: <role-name>           # Kebab-case, prefixed with `forge-`
description: <what it does>  # One sentence
---

Body structure: Title and identity statement → Behavior rules → Output format → Constraints (if any). The body is composed with task-specific instructions from the skill at delegation time.

Role names are prefixed with forge- to avoid shadowing generic names (scout, reviewer) that bundled runtimes may use.

Bash Examples in Skills

• Every gh command must be a valid GitHub CLI command (used in GitHub provider paths)
• Use placeholder syntax consistently: <ISSUE_NUMBER>, <OWNER>, <REPO>, <BRANCH_NAME>
• Include comments in multi-step bash blocks explaining each command
• Show both the command and the expected usage pattern
• When reading repository files in examples, prefer the Read tool over shelling out with cat

Cross-Skill Consistency

Conventions shared across skills. When modifying any, update every skill that references them:

Convention	Format	Referenced In
Conventional commits	<type>(<scope>): <description> — titles, branches, commits, PRs	create-issue, implement, address-pr-feedback
Canonical guidance file	AGENTS.md canonical; CLAUDE.md compatibility symlink	setup-project, implement, reflect
Validate approach	Present plan and get user confirmation before implementing (skipped in unattended mode)	implement, ship
Phase execution	Pre-flight, per-phase implementation/testing loop, phase gates — kept inline in implement so the default execution path does not need extra reference files	implement
Pattern audit	When changing a pattern, update ALL files using it	implement, reflect
Mandatory deferred tracking	Create Issues (in the project's Issue tracker) for all deferred items found in reflection	reflect
Trailing context syntax	Append -- <additional context> as the final invocation segment for skills with structured primary input	setup-project, shape, implement, reflect, address-pr-feedback
Review severity	P0-P3 (see _shared/review-rubric.md)	reflect, ship
Sub-agent delegation	context: fork frontmatter + (delegate) step marker with role reference or self-contained instructions and inline fallback	shape, implement, reflect
Review delegation	Tiny low-risk diffs stay inline; otherwise use one fresh-context reviewer by default and add a second focused pass only for high-risk or broad diffs. Consolidated in _shared/review-delegation.md; inline fallback executes the same lean shape sequentially	reflect, ship
One question at a time	Ask convergent questions one at a time with recommended answers; do not batch (see shape/references/shaping-methodology.md)	shape
Challenge then converge	Push back on terminology conflicts with CONTEXT.md, code contradictions, and vague boundaries; invent concrete scenarios to stress-test fuzzy edges	shape
Vocabulary discipline	Use CONTEXT.md terms when framing questions; update CONTEXT.md inline when terms are resolved during shaping; add _Avoid_ aliases for rejected synonyms	shape
Explore before asking	Check if codebase answers each question before asking the user; provide recommended answers	shape
Divergent sub-agents	(delegate) step with parallel sub-agents, each given radically different constraints for approach contrast; inline fallback generates sequentially (see "Writing Delegate Steps")	shape (Step 3, optional)
Vertical slices	Split issues as thin end-to-end paths across all layers; classify as AFK or HITL	create-issue
Reusable roles	Sub-agent personas under roles/ — skill-specific roles co-locate with the skill; cross-skill roles live in _shared/roles/	implement (forge-scout), reflect + ship (forge-reviewer in _shared/)
Blind research delegation	(delegate) research step using forge-scout role — receives questions but not the ticket; inline fallback answers factually without suggesting implementations	implement
Structure outline	High-level vertical phases with verification steps; each phase is a testable end-to-end slice	implement
Durable decisions	Identify architectural decisions that survive implementation changes; keep as plan header	implement
Skill composition	Composite skills reference other skills by path; orchestrators stay lean	ship
Tool-layer integration	Reference external tools (e.g., subagent) by name with inline fallback	ship
Unattended mode	--unattended flag skips user interaction; plan approval auto-proceeds, triage fixes in-scope findings by default and defers only truly larger or out-of-scope items	ship, implement
Issue tracker providers	Provider operations consolidated in _shared/issue-operations.md; skills reference it instead of inlining conditionals	create-issue, implement, reflect, ship, shape, address-pr-feedback
Workflow order	setup → [shape →] create → implement → reflect → address; ship composes implement + reflect	All skills

Instruction Budget

Frontier LLMs follow ~150-200 instructions with good consistency. Beyond that, adherence degrades and steps get skipped unpredictably. Since skills share the context window with AGENTS.md, system prompts, and tool definitions, keep individual skills lean:

• Target: under 35 distinct instructions per skill. Count each directive, conditional, and behavioral rule.
• Delegate when growing past the budget. Use sub-agent delegation to offload self-contained concerns (research, review, approach generation) into fresh context windows.
• Prefer the minimum effective reviewer count. For review, keep tiny low-risk diffs inline, otherwise start with one focused fresh-context reviewer and deepen only when risk clearly justifies another pass.
• Match model cost to task shape. Factual scouting should use cheap fast models when the runtime supports per-task model choice; routine review should prefer cheaper review-capable models; save the strongest models for synthesis, planning, and hard implementation decisions. If the runtime cannot vary models per task, the skill should still work by inheriting the parent session model.
• Don't use prompts for control flow. If a skill has multi-way branching (mode selection, input type routing), split into focused skills or use a lightweight routing step.

Style Rules

• Use **bold** for emphasis on key terms and warnings
• Use > blockquote for example dialogue or user-facing messages
• Use tables for structured reference data
• Use fenced code blocks with language hints (bash, markdown, json)
• Keep lines under 120 characters where practical
• Use em dashes (—) not hyphens for parenthetical clauses in prose