Skills: Registry & Discovery

Forge treats skills — reusable capability files that subagents load by path — as first-class project assets. The design is index-first: a registry catalogs what's installed and hands out exact paths, and an opt-in discovery flow suggests what else might help. Nothing is summarized, and nothing is installed behind your back.

Commands

forge skill-registry refresh
forge skill-discover [--source <name>] [<search>] [--install <id>]

The registry lives at .forge/skill-registry.md. Discovery is also reachable in-agent as /forge.discover.

The registry is an index, not content

skill-registry refresh scans skill roots and rebuilds .forge/skill-registry.md. It scans project-scoped roots first, then global-scoped roots, and records one row per skill:

Field	Meaning
Name	The skill's name from frontmatter, or its directory name
Scope	project or global
Description	The full description, verbatim — folded multiline included
Path	The exact SKILL.md file to open on disk

Two rules keep the index clean:

• Project wins the dedup. When a project-scoped and a global-scoped skill share a name, the project copy wins and the global one is dropped.
• Plumbing is excluded. Orchestrator and internal skills — the exact names _shared and skill-registry, plus anything matching sdd-* — never enter the index. The exclusion is silent, so a user skill whose name collides with those prefixes is dropped without a warning.

Unreadable roots and malformed SKILL.md files are skipped rather than raised, so one broken third-party skill never breaks the refresh. Run it whenever skills are added, removed, renamed, or moved. Where the agent supports startup hooks, normal installs wire the refresh in for you.

The registry never substitutes for the skill

The index records the description and the path — it does not embed the skill's instructions. Treating the one-line description as a stand-in for the real SKILL.md is explicitly wrong. The registry exists to route an agent to the exact file; the file remains the source of truth.

The exact-path runtime contract

Index-first exists to protect author intent. Compact summaries are cheap to inject but distort skills — nuance gets lost, custom skills break. Forge spends tokens only when a subagent actually needs a skill, and it spends them on the real file.

The delegator passes paths, not digested rules:

## Skills to load before work

Read these exact files before reading, writing, reviewing, testing, or creating artifacts:

- /abs/path/to/.claude/skills/go-testing/SKILL.md
- /abs/path/to/.forge/skills/docs-writer/SKILL.md

The subagent opens those files and works from them. The original SKILL.md is never summarized in transit — its author's intent survives the delegation intact.

Discovery — what else might help

Where the registry answers "what's installed?", forge skill-discover answers a different question: "what else, outside this project, might help with the feature I'm working on right now?"

1. Profile the need from the detected stack — marker files such as package.json, go.mod, Cargo.toml, pyproject.toml — plus keywords pulled from the current change's spec and tasks.
2. Query configured sources. Each returns candidates as {name, source, description, why}.
3. Rank. Skills already available locally are always listed first; other sources follow, ranked by keyword overlap against the profile.
4. Present, don't act. Results are a table for you to review. --install <id> is the separate, explicit step you take afterward — it fetches the chosen skill into .forge/skills/, and discovery alone installs nothing.

Discovery is conservative by design: it never auto-installs, stores no credentials, and degrades cleanly offline — an unreachable source contributes nothing and discovery continues with whatever the remaining sources returned, which is treated as expected, not an error.

Building new skills and agents

New skills and subagents don't have to be hand-written. Forge exposes an agent-driven interactive builder: an agent workflow that turns authoring into a short interview and guarantees the output is validated before it touches disk.

The interview walks one question at a time — name and purpose, trigger, tools and permissions, target adapters, persona and tone, then hard MUST / MUST NOT rules collected until you have nothing left to add. The answers render into a single Markdown file with YAML frontmatter (name and description) and a mandatory ## Rules section.

Validation is non-negotiable

A file that fails validation is never installed. The frontmatter must be parseable YAML with a non-empty name and description, and the body must carry a ## Rules section. The full rendered file is previewed exactly as it will land, and nothing installs until you confirm. On a successful install, .forge/skill-registry.md is rebuilt automatically — best-effort, so a refresh failure never undoes the install.

Installed skills land under .claude/skills/<name>/SKILL.md (and .agents/skills/ too when that directory exists); agents land under .claude/agents/<name>.md. Either way the new capability shows up in the registry on the next refresh, ready for the delegator to route.

Next steps

• Command Reference — the full skill-registry and discovery surface.
• Supported Agents — how skills and agents fit the adapter model.
• Configuration — where skill sources and roots are set.
• The Workflow — where skills load during a change.