# 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

```sh
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`.

```mermaid
flowchart TD
  PR["Project roots<br/>.forge/skills, .claude/skills, ..."] --> RF[skill-registry refresh]
  GL["Global roots<br/>~/.claude/skills, ..."] --> RF
  RF --> DD["Dedupe by name<br/>project wins over global"]
  DD --> EX["Exclude plumbing<br/>_shared, skill-registry, sdd-*"]
  EX --> REG[".forge/skill-registry.md<br/>index: name + description + path"]
```

## 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.

::: warning 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**.

```mermaid
flowchart TD
  U[User task] --> O["Orchestrator reads<br/>.forge/skill-registry.md"]
  O --> M["Match task + file context<br/>against full descriptions"]
  M --> P[Pass exact SKILL.md paths to subagent]
  P --> R[Subagent reads full skills before work]
  R --> E[Subagent executes with original intent preserved]
```

The delegator passes paths, not digested rules:

```markdown
## 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?"

```mermaid
flowchart LR
  P["Capability profile<br/>stack + spec/tasks keywords"] --> Q[Query configured sources]
  Q --> R["Rank<br/>local first, then keyword overlap"]
  R --> S["Present as a table"]
  S --> C["User confirms — nothing auto-installed"]
```

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.

::: info 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](/guide/commands) — the full skill-registry and discovery surface.
- [Supported Agents](/guide/agents) — how skills and agents fit the adapter model.
- [Configuration](/guide/configuration) — where skill sources and roots are set.
- [The Workflow](/guide/workflow) — where skills load during a change.