g-skill-design · diff
git:20260722.4b86922 to git:20260831.81b585b
10 added, 9 removed. Audit A to A.
---
name: g-skill-design
- description: Design a new G-Forge skill from scratch. Gathers requirements, drafts SKILL.md with correct structure, and adds a single bare-token routing line to the g-forge router.
+ description: Design a new G-Forge skill from scratch. Gathers requirements, drafts SKILL.md with correct structure, and registers the new skill's bare token on all three router surfaces.
---
**Announce:** "Using g-skill-design to design the new skill."
You are designing a new G-Forge skill. Follow these steps in order.
## Step 1 — Understand the skill's purpose
Ask the developer:
> "What should this skill do? Describe:
> 1. The trigger — what user action or workflow state invokes it?
> 2. The output — what does running this skill produce? (files, reports, modified state, user guidance)
> 3. The name — what will the skill be called? (e.g. `foo` → `skills/g-foo/SKILL.md`, invoked directly as its own entry or via `/g-forge foo`)"
Wait for answers before continuing.
## Step 2 — Check for existing similar skills
Use Glob to list `skills/*/SKILL.md`. Read the `description:` line from the frontmatter of each. If a skill with substantially similar purpose already exists, tell the developer:
> "A similar skill already exists: [name] — [description]. Should we extend that one or create a new one?"
Wait for answer. If extending, stop here and provide notes on what to change; do not write a new file.
## Step 3 — Draft the skill steps
From the developer's answers, draft the numbered steps the skill will follow. Each step must:
- Have a clear single responsibility (read, ask, draft, write, dispatch, or report)
- Specify wait points (when to pause for user input before proceeding)
- Not invoke the Skill() tool (use Glob+Read on the target SKILL.md instead)
- Not write a file before reading it first
Present the step outline to the developer:
> "Here is the proposed step outline — does this match what you want?"
Wait for approval or revision before writing anything.
## Step 4 — Write the SKILL.md
Write `skills/g-[name]/SKILL.md` with this structure:
```
---
name: g-[name]
description: [One sentence: what it does and when to use it.]
---
**Announce:** "Using g-[name] to [purpose]."
[Intro sentence describing what this skill does.]
## Step 1 — [Verb phrase]
[Step body]
## Step 2 — [Verb phrase]
[Step body]
[... remaining steps ...]
## Rules
- [Rule protecting against the most common mistake]
- [Rule protecting against the second most common mistake]
[... additional rules as needed ...]
```
**Required elements — verify before writing:**
- YAML frontmatter with `name:` and `description:` only (no `argument-hint`)
- `**Announce:**` line immediately after the closing `---` of frontmatter
- All steps numbered `## Step N — [Verb phrase]`
- At least one rule in `## Rules`
- No Skill() tool invocations anywhere in the file
- No hardcoded absolute paths (use Glob to discover dynamic paths)
- ## Step 5 — Add a bare-token routing line to the g-forge router
+ ## Step 5 — Register the bare token on all three router surfaces
- Read `commands/g-forge.md`. Make two additions only — no per-skill prose (ADR-007: prose in the router re-opens the drift axis the ADR closed):
+ Read `commands/g-forge.md`. Make three additions — all bare tokens, no per-skill prose (ADR-007: prose in the router re-opens the drift axis the ADR closed):
- 1. In the `argument-hint` value: append `|[name]` to the pipe-separated list
- 2. In the routing table: add a new bare-token line `- \`[name]\` → \`skills/g-[name]/SKILL.md\`` — no description, no prose
+ 1. In the frontmatter `description:` value: append the new token to the comma-separated subcommand list (before the closing period)
+ 2. In the `argument-hint` value: append `|[name]` to the pipe-separated list
+ 3. In the routing table: add a new bare-token line `- \`[name]\` → \`skills/g-[name]/SKILL.md\`` — no description, no prose
- Do not add anything to the subcommand description list at the bottom for the new skill.
+ Add nothing else anywhere in the router — it carries no per-skill prose on any surface (ADR-007). `tests/test-router-skill-parity.sh` pins all three token surfaces against `skills/` and against each other; run it after the router edit.
Write the updated file.
## Step 6 — Report
```
Skill created ✓
✓ skills/g-[name]/SKILL.md — skill workflow written
- ✓ commands/g-forge.md — bare-token router line added
+ ✓ commands/g-forge.md — bare token registered on all three surfaces
Run /g-skill-validate [name] to validate the new skill's structure.
```
## Rules
- Never write SKILL.md before Step 3 approval — the step outline must be confirmed first.
- Never use Skill() tool invocations in the generated SKILL.md.
- Never add argument-hint to SKILL.md frontmatter.
- If a similar skill already exists, surface it before drafting — do not create duplicates.
- - Never create a companion `commands/g-[name].md` file — per ADR-007, `skills/g-[name]/SKILL.md` is the sole authored source; only a bare-token routing line is added to `commands/g-forge.md`.
- - The router addition must be a bare token — no prose, no description — and must not touch the subcommand description list.
+ - Never create a companion `commands/g-[name].md` file — per ADR-007, `skills/g-[name]/SKILL.md` is the sole authored source; only a bare token is registered across the router's three surfaces in `commands/g-forge.md`.
+ - Every router addition is a bare token — no prose, no descriptions — on each of the three token surfaces (description list, argument-hint, routing list); the parity suite pins them against each other.
- Router update must preserve all existing entries — read before writing.