Maintaining

# Adding a skill to the payload

Adding a skill to WongStack means creating it under [`.agents/skills/`](../../.agents/skills/) and wiring it through every surface that installs, versions, and advertises the payload — so [`/wong-sync`](../../.agents/skills/wong-sync/SKILL.md) pulls it into target repos, and the docs and READMEs still match reality. It's a [release](README.md), so it ends with a changelog entry.

A skill that stays in WongStack, like [`update-dependencies`](../../.agents/skills/update-dependencies/SKILL.md), does step 1 only. It gets no `payload-files.json` entry, no setup surface names it, and its edits need no changelog entry of their own. The manifest guide lists these skills under [Not copied](../../.agents/skills/wong-sync/references/payload-manifest.md#not-copied); the [link check](../../.agents/rules/payload.md) still resolves their links, headings included, against this repo.

Work through it in order:

1. **Create the skill.** Add `.agents/skills/<name>/SKILL.md` with YAML frontmatter — `name`, a one-line `description` that says what the skill does and when to use it, like the others (the text an invocation is matched against), and `user-invocable: true` — following [`save`](../../.agents/skills/save/SKILL.md) for shape. Add a `references/` folder for supporting material the skill reads (as [`wong-sync`](../../.agents/skills/wong-sync/references/) does) and/or a `scripts/` folder for helpers it runs (as [`save`](../../.agents/skills/save/) does), only if the skill needs them. A script there takes `isMain` and `parseCli` from the shared [`memory/scripts/lib/cli.mjs`](../../.agents/skills/memory/scripts/lib/cli.mjs), never its own copy: skills already import that folder, and a copy drifts. A runbook long enough to displace what the skill *is* belongs in `references/` rather than in `SKILL.md` — see [repo layout](repo-layout.md) for where a payload file physically lives before you edit it. The skills' text is budgeted: [`measure-context.mjs --check`](../../scripts/measure-context.mjs) fails when the instruction total or the session's start-up words grow, so a new skill needs a cut elsewhere, by [the payload rule](../../.agents/rules/payload.md). A skill only a person should start, like [`dream-memory`](../../.agents/skills/dream-memory/SKILL.md), takes `disable-model-invocation: true`: no session loads its description, and its files are counted apart as `on-call`. The Skill tool refuses such a skill too, so never set it on a verb another verb hands off to. Reference repo files by **repo-relative path** — `$(git rev-parse --show-toplevel)/…` — never an absolute path or `${CLAUDE_PLUGIN_ROOT}`, because the same skill runs from whatever repo installed it.

2. **Wire it into the payload inventory.** Add the directory name to `core.skillDirs` in [`payload-files.json`](../../.agents/skills/wong-sync/references/payload-files.json). That machine-readable file is the one source of truth for fresh setup, sync, and payload link checks; its companion [manifest guide](../../.agents/skills/wong-sync/references/payload-manifest.md) owns the rules. The installer copies the whole skill directory, including `references/` and `scripts/`. A target's install record maps upstream names to local names, so setup and sync preserve a target-owned skill with the same name instead of silently replacing it. Update a setup surface only when that surface separately names the skill; do not create a second copy-list.

3. **Cut a minor release** by [the payload rule](../../.agents/rules/payload.md): a new skill is additive, and without a changelog entry existing installs never hear of it.

4. **Update the user-facing surfaces.** Add its operating rule to the `WONG-STACK:BEGIN/END` block in [`AGENTS.md`](../../AGENTS.md) when every installed repo must know it. Link its owning workflow page from the [development hub](../development/README.md). These are what a reader and a freshly installed repo see.

5. **Carry attribution for adapted work.** If the skill adapts external, licensed work, keep the required license material with the skill and record a `license:` field and source metadata in the SKILL frontmatter.

Part of [maintaining WongStack](README.md).