/skill-forge

name: skill-forge
description: Use when the user asks to forge, scaffold, author, or ship a new skill or agent — the skill-creator's own namesake artifacts. Drives the skill-forge loop (create → fill → validate → critique → ship → publish) via the skill-creator CLI.
description-frequency: on-demand
user-invocable: true
version: 1.0.0
format: 2025-10-02
triggers:
  - "the user asks to create, scaffold, or author a new skill or agent"
  - "the user wants to ship or publish a skill through its quality gates"
updated: 2026-07-12
status: ACTIVE

Skill Forge

Forge a new skill or agent end-to-end using the `skill-creator` CLI. The forge is the toolchain that scaffolds, validates, and ships skills and agents; this skill is the playbook that drives it.

When to invoke

Trigger on any of:

• "create a skill for X" / "author a new skill"
• "scaffold a skill" / "make me a skill that …"
• "add an agent" / "author a subagent for X"
• "ship this skill" / "run the skill through its gates"

Do **not** trigger for:

• Editing an existing skill's guidance — that is

`skill-creator refine <name>` (corrections, not a new artifact).

• Retiring a skill — that is `skill-creator skill retire <name>`

(suggest-first, reversible).

• Forging a **cartridge** (content / department / chipset bundle) —

that is the `cartridge-forge` skill.

Prerequisites

1. `docs/SKILL-FORMAT.md` is the normative frontmatter/format reference; `docs/skill-authoring/skill-md-quality-checks.md` lists the hard defects the gate rejects; `docs/authoring-tools.md` maps the CLI surface. Read them once per session if the context is not already loaded. 2. Pick the slug (kebab-case, matches the skill `name:`). Keep it specific — the description and triggers must not collide with an existing skill's activation. 3. Decide **skill vs agent**. A skill is auto-loading guidance (a `SKILL.md`); an agent is a delegated subagent with its own tool set (an `agents/<name>.md`). Author the one the task needs.

The Forge Loop

create → fill → validate → critique → ship → publish

Every step is idempotent. `skill ship` is the gate — if it exits non-zero, the skill is not ready to publish.

1. Create

skill-creator create

The wizard scaffolds a spec-valid `SKILL.md`: repo-canonical frontmatter (`version` / `format` / `status: ACTIVE`) plus a body seeded from a template preset (workflow-guide / reference / checklist) rather than a blank prompt. It prints a `Next: validate → critique → ship` footer.

For an agent instead of a skill:

skill-creator agents create --name=<slug> --description="…"

(or run it interactively). It delegates to the AgentGenerator and writes a spec-valid agent `.md` with comma-separated `tools`.

2. Fill

Replace the template body with real guidance. A well-formed skill body typically wants:

• A one-line intro naming what the skill drives.
• A **When to invoke** section with concrete trigger phrases and an

explicit do-**not** list (the highest-signal way to keep two on-demand skills from co-activating).

• The working steps — commands, rules, or a decision procedure.
• An **Output contract** if the skill produces a deliverable.

Keep the frontmatter `description` and `triggers` distinct: a trigger that is a verbatim-truncated copy of the description is a hard defect (see step 3).

3. Validate

skill-creator validate <name>

Runs the skill-content gate: it **blocks** on structural threats (unsafe YAML, path traversal, schema violation, secret in frontmatter) and **sanitizes-and-warns** on in-body issues. A clean exit is required.

4. Critique

skill-creator critique <name>

Surfaces quality issues (thin triggers, missing sections, vague description) that validate does not hard-block. Address the findings before shipping.

5. Ship

skill-creator skill ship <name>

Runs the ship pipeline in order — **validate → critique → test-triggering** — with a per-gate verdict. Exit code `0` means `<name>` is ship-ready. This is the equivalent of cartridge-forge's `eval` gate: do not report "done" before it is green. Use `--mock` to dry-run the pipeline.

For an agent, the parallel gate is:

skill-creator agents validate

which now exits non-zero on spec defects.

6. Publish

skill-creator publish <name>

Promotes the ship-ready skill. Only run after `skill ship` is green.

Rules

1. **Never hand-edit a skill under `.claude/skills/`.** That tree is gitignored and self-mod-guarded; the tracked source is `project-claude/skills/`. Author there and let `node project-claude/install.cjs` deploy it. 2. **Never skip `skill ship`.** It is the publish gate. 3. **A correction is not a new skill.** Route "the skill got X wrong" to `skill-creator refine`, not a fresh `create`. 4. **Keep triggers distinct from the description** and from other skills' triggers — co-activation is a real cost on every session. 5. **Commit the SOURCE only** (`project-claude/…`), never `.claude/…` — the git-add-blocker enforces this.

Reference walkthrough

A well-formed recent skill to model: `project-claude/skills/skill-frontmatter-doctor/SKILL.md` — a single-file, on-demand skill with a tight description, distinct triggers, and a clear defect-detection procedure.

Output contract

After the loop completes, report to the user:

• Final `name`, artifact kind (skill / agent), and source path.
• Frontmatter shape: `version` / `format` / `status`.
• `validate / critique / ship` verdicts (each shown green).
• Whether it was deployed (`install.cjs`) and published.

Do not report "done" before `skill ship` (or `agents validate`) has been run and shown green.