---
name: forge
description: >
  Use when the user wants something built or improved but has not yet named
  its type ("skill or plugin?"). If named, use instead: skill -> `skill-author`,
  agent -> `agent-author`, hook/instruction/prompt -> `primitive-author`,
  plugin -> `apm-workflow`.
metadata:
  version: "1.0.2"
  category: factory
  source_keys:
    - claude-code-subagents-docs
    - context7-websites-code-claude
    - agentskills-spec
---

## Gotchas

- Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite the shared word: `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. The route reference each classification loads spends that distinction: `references/author-routes.md` chooses between a `/fork` subagent and an inline run, and `references/apm-routes.md` rules the fork out.

## Step 1 — Grill the intent

Call `grill-with-docs` unless a grill session has already run and is available in the context.

If `grill-with-docs` does not resolve, read `references/grill-fallback.md`.

Grilling often overturns or splits the assumed type, so it runs before classification, inline — a subagent cannot hold the back-and-forth.

## Step 2 — Classify and dispatch

Match the grilled intent against exactly one row — or more than one, if the intent genuinely spans several artifacts.

| Intent | Artifact type | Route to | Read |
|---|---|---|---|
| A reusable capability the agent loads inline in the main conversation, triggered by description-matching, free to bundle its own `references/`, `scripts/` or `assets/` | Skill | `skill-author` | `references/author-routes.md` |
| A recurring task needs its own reusable definition — dedicated system prompt, tools and description, invokable by name across sessions | Agent / subagent | `agent-author` | `references/author-routes.md` |
| A runtime callback at a harness event, a rule scoped to a file pattern, or a reusable user-typed message steering existing skills or agents | Hook / instruction / prompt | `primitive-author` | `references/author-routes.md` |
| A new distributable unit — no existing plugin is the right home for the skill, agent, hook or MCP server being built, or the bundle needs its own manifest, versioning and install lifecycle | Plugin | `apm-workflow` (`apm plugin init`) | `references/apm-routes.md` |
| The plugin already exists and only its marketplace-facing metadata changes — a first listing, or a version/description update, never the plugin's contents | Marketplace entry | `apm-workflow` (`apm marketplace package add`) | `references/apm-routes.md` |

The table classifies what to build, not how to run it: a one-off task that merely needs an isolated or context-inheriting run is not an artifact and has no row here. If the intent stays genuinely ambiguous between rows after grilling, ask the user rather than guessing.

A real artifact that matches no row — an MCP server, an AGENTS.md, a research doc — has no route here. Say so, hand the user the skill that does own it, and never bend it into a row to make the table fit.

When the intent spans several rows, chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first, so `apm-workflow` scaffolds the plugin directory before `skill-author` scaffolds a skill inside it.

**Announce, then invoke.** State the classification and which skill(s) will run. Then read the reference file for each classified artifact type — only those — and follow it.

## Step 3 — Closing gates, common to every route

- **Resolve before closing.** A route is finished only when its verification reports nothing unresolved. An actionable finding reopens the route; it is never reported onward as a caveat.
- **Bump the package version.** A skill route always lands here: `skill-author` moves only a skill's own `metadata.version`, which is not the package `apm.yml`'s number — so read `references/version-bump.md` after one; it skips the bump when the branch already has one. `agent-author`, `primitive-author` and the apm routes bump the package themselves at plugin scope; after those, read it only when their output says neither that they bumped nor that the branch already had.