Catalog
This skill is for this repository. How to work here in general:
AGENTS.md. Load adapter:
.agents/README.md.
A published skill is a pattern other projects install. Project values do not
belong in it.
Houses
| File |
Owns |
skills/<name>/SKILL.md |
Pattern. Agent prompt. YAML frontmatter name + description. |
skills/<name>/README.md |
The human page, under about 400 words: a diagram if one helps, then What it does (with the one defining constraint), When to reach for it (invocation mode and the trigger boundary), It's working if (tells a reader can check without opening SKILL.md), Where it fits, What it does to your machine (writes, downloads, runs, undo, as a table; one line when it only reads), Apply to a project, Pointers. |
skills/<name>/references/ |
The long facts: fields, registry, CLI tables, state machines. The README and SKILL point here; neither restates them. |
skills/<name>/examples/ |
Shape of values, not a required backend. |
skills/<name>/agents/openai.yaml |
Codex picker metadata: interface.display_name, interface.short_description; for a user-invoked skill also policy.allow_implicit_invocation: false. |
.agents/skills/<name> |
Relative symlink to ../../skills/<name>. |
.claude-plugin/plugin.json |
The plugin manifest: every published skill in skills, nothing else. CI diffs the two. |
Root README.md Skills table |
One-line index, grouped user-invoked / model-invoked. |
infra/addressing.yml |
This checkout's TLD and hostname scheme. Clone override: addressing.local.yml. |
name in frontmatter equals the directory name.
Invocation
Every skill is one of two:
- Model-invoked (the default): a model or a person may reach for it.
The description is model-facing and keeps its trigger phrases ("Use
when…",
/name). Grove, Dryad, Understory, Mycelium: a seat reaches for
them on its own when its work meets them.
- User-invoked: only a person typing
/name. Frontmatter carries
disable-model-invocation: true and agents/openai.yaml carries
policy.allow_implicit_invocation: false; the two are always set
together or neither. The description is human-facing, one or two
sentences, no trigger list. Forester: the plan is a person's ask.
A skill that tells the agent to run another skill says so as a tool call,
one skill per call: Call the Skill tool with "dryad". A relative link
([dryad](../dryad/SKILL.md)) is router prose for a person and fires
nothing. Nothing may name a user-invoked skill to the Skill tool; tell the
person to run it instead. In a host with no Skill tool the same sentence
means: read that skill's SKILL.md from the installed copy (a seat has
Dryad's path in $DRYAD_SKILL; the others sit beside it) and follow it.
That fallback is the root README's, stated once; skills do not repeat it.
Add a skill
- Create
skills/<name>/SKILL.md. Pattern only — no domains, ports, service
lists, or real commands. Those go in a consuming project's
.agents/runtime-profile.yml (Grove) or the equivalent values file the
skill names.
- Write
README.md next to it in the seven-section shape above, and put
every field or CLI table in references/. Do not paste the SKILL body
into the README; point.
- Decide the invocation (above) and write
agents/openai.yaml.
ln -s ../../skills/<name> .agents/skills/<name>- Add the path to
.claude-plugin/plugin.json skills, then
claude plugin validate . --strict.
- Add one row to the root README Skills table, in its invocation group.
- Public surfaces are English.
- If the skill has parser or CLI behavior in
infra/, add tests under
infra/bin/ and revert the production change once to see the new test
go red. Then npm test.
Tool dirs (.claude/skills, .cursor/skills, .grok/skills) already point
at .agents/skills. Do not copy the skill there.
Do not add the new skill's pattern to AGENTS.md. Point at skills/<name>/.
Edit a skill
Change the house that owns the fact. If the same sentence exists in SKILL
and README, edit the owner and make the other a pointer.
Grove-specific: schema lives in references/runtime-profile.md; invariants
are judged in infra/lib/profile.mjs. Do not restate the schema in SKILL.md.
Not this skill
- Planting Grove on another repo →
grove
- Starting or stopping machine engines →
infra/ CLI, and only when asked
- Changing how agents work in this catalog (invariants, verify, no-down) →
AGENTS.md
1---2name: catalog3description: Add, edit, rename, or review a published skill in the de-novo skills catalog (skills/<name>/). Use when creating a new skill, splitting SKILL.md vs README vs examples, wiring .agents load paths, updating the catalog README table, or when the user runs /catalog. Not for planting Grove on a consuming project — that is grove.4---56# Catalog78This skill is for **this repository**. How to work here in general:9[`AGENTS.md`](../../../AGENTS.md). Load adapter:10[`.agents/README.md`](../../README.md).1112A published skill is a pattern other projects install. Project values do not13belong in it.1415## Houses1617| File | Owns |18| --- | --- |19| `skills/<name>/SKILL.md` | Pattern. Agent prompt. YAML frontmatter `name` + `description`. |20| `skills/<name>/README.md` | The human page, under about 400 words: a diagram if one helps, then **What it does** (with the one defining constraint), **When to reach for it** (invocation mode and the trigger boundary), **It's working if** (tells a reader can check without opening SKILL.md), **Where it fits**, **What it does to your machine** (writes, downloads, runs, undo, as a table; one line when it only reads), **Apply to a project**, **Pointers**. |21| `skills/<name>/references/` | The long facts: fields, registry, CLI tables, state machines. The README and SKILL point here; neither restates them. |22| `skills/<name>/examples/` | Shape of values, not a required backend. |23| `skills/<name>/agents/openai.yaml` | Codex picker metadata: `interface.display_name`, `interface.short_description`; for a user-invoked skill also `policy.allow_implicit_invocation: false`. |24| `.agents/skills/<name>` | Relative symlink to `../../skills/<name>`. |25| `.claude-plugin/plugin.json` | The plugin manifest: every published skill in `skills`, nothing else. CI diffs the two. |26| Root `README.md` Skills table | One-line index, grouped user-invoked / model-invoked. |27| `infra/addressing.yml` | This checkout's TLD and hostname scheme. Clone override: `addressing.local.yml`. |2829`name` in frontmatter equals the directory name.3031## Invocation3233Every skill is one of two:3435- **Model-invoked** (the default): a model or a person may reach for it.36 The description is model-facing and keeps its trigger phrases ("Use37 when…", `/name`). Grove, Dryad, Understory, Mycelium: a seat reaches for38 them on its own when its work meets them.39- **User-invoked**: only a person typing `/name`. Frontmatter carries40 `disable-model-invocation: true` and `agents/openai.yaml` carries41 `policy.allow_implicit_invocation: false`; the two are always set42 together or neither. The description is human-facing, one or two43 sentences, no trigger list. Forester: the plan is a person's ask.4445A skill that tells the agent to run another skill says so as a tool call,46one skill per call: `Call the Skill tool with "dryad"`. A relative link47(`[dryad](../dryad/SKILL.md)`) is router prose for a person and fires48nothing. Nothing may name a user-invoked skill to the Skill tool; tell the49person to run it instead. In a host with no Skill tool the same sentence50means: read that skill's `SKILL.md` from the installed copy (a seat has51Dryad's path in `$DRYAD_SKILL`; the others sit beside it) and follow it.52That fallback is the root README's, stated once; skills do not repeat it.5354## Add a skill55561. Create `skills/<name>/SKILL.md`. Pattern only — no domains, ports, service57 lists, or real commands. Those go in a consuming project's58 `.agents/runtime-profile.yml` (Grove) or the equivalent values file the59 skill names.602. Write `README.md` next to it in the seven-section shape above, and put61 every field or CLI table in `references/`. Do not paste the SKILL body62 into the README; point.633. Decide the invocation (above) and write `agents/openai.yaml`.644. `ln -s ../../skills/<name> .agents/skills/<name>`655. Add the path to `.claude-plugin/plugin.json` `skills`, then66 `claude plugin validate . --strict`.676. Add one row to the root README Skills table, in its invocation group.687. Public surfaces are English.698. If the skill has parser or CLI behavior in `infra/`, add tests under70 `infra/bin/` and revert the production change once to see the new test71 go red. Then `npm test`.7273Tool dirs (`.claude/skills`, `.cursor/skills`, `.grok/skills`) already point74at `.agents/skills`. Do not copy the skill there.7576Do not add the new skill's pattern to `AGENTS.md`. Point at `skills/<name>/`.7778## Edit a skill7980Change the house that owns the fact. If the same sentence exists in SKILL81and README, edit the owner and make the other a pointer.8283Grove-specific: schema lives in `references/runtime-profile.md`; invariants84are judged in `infra/lib/profile.mjs`. Do not restate the schema in SKILL.md.8586## Not this skill8788- Planting Grove on another repo → `grove`89- Starting or stopping machine engines → `infra/` CLI, and only when asked90- Changing how agents work in this catalog (invariants, verify, no-down) →91 `AGENTS.md`
de-novo