# Repo Conventions

Local rules for authoring skills in this repository.

## Source of truth

Edit sources under `src/`; `dist/` is generated by `make build` and committed.

- `src/skills/<name>/SKILL.md` — base skill body and shared frontmatter
- `src/skills/<name>/references/`, `scripts/`, `assets/` — support files copied
  with the skill
- `src/skills/<name>/.agentbundler/targets/<target>.json` — target sidecar
- `src/.agentbundler/packages/<package>.json` — package ownership and shipping
  surface

Agent Bundler loads the base `SKILL.md`, applies the target sidecar, adds the
target-wide composition preamble from `agentbundle.json`, then copies support
files. `targets:` in base frontmatter restricts which targets a source ships to
and does not leak into emitted frontmatter. All enabled targets ship under
package-owned paths. Gemini is retired.

## Target-only content

`make validate` rejects these tokens in a base `SKILL.md` or agent file:
`$ARGUMENTS` and `$1`-style arguments, `Task(`, `AskUserQuestion`,
`TaskCreate`, `TodoWrite`, `mcp__*` tool IDs, `` !`cmd` `` preprocessor
backticks, and `${CLAUDE_*}` variables. Put them in the target sidecar, along
with target-only frontmatter such as `allowed-tools`, `context`,
`user-invocable`, and `model`.

Sidecar fields are `frontmatterPatch`, `bodyPatch`, `files`, and
`deletedFiles`. `bodyPatch.mode` is one of:

- `sections` — replaces the body of existing, unique headings. `headingPath` is
  the full heading chain from the H1, for example
  `["Instruction Review", "Platform additions"]`. The replacement runs from the
  line after the heading to the next heading at the same or higher level. Start
  the patch body with a newline and use `###` or deeper inside it. A missing or
  ambiguous path fails the build.
- `replace` — replaces the whole body. Use it only for a deliberate full fork.

Write sidecar JSON with a script (`json.dump`) rather than hand-escaping
newlines. After `make build`, open
`dist/claude/<package>/skills/<name>/SKILL.md` and confirm it holds the base
body, its reference links, and the patched section.

## Adding, removing, or renaming a skill

- Add or remove the skill path in `src/.agentbundler/packages/<package>.json`.
- Update `tests/skill-evals/**`, tests, and `README.md` mentions that name it.
- Check `AGENTS.md` when it lists the public skill surface.
- Run `make build` so removed output disappears from `dist/`.

## Checks

```bash
make build   # needs the sandbox disabled: the uv cache is restricted
make check   # generated drift
make ci      # lint + validate + check + test + test-ts
```

`make lint-instructions` is an advisory structural pass over the repo; the
reviewing-instructions skill makes the quality call.

## Neighbor skills

Check these before creating a new skill; a small twist on one of them usually
belongs inside it:

- `reviewing-instructions` — scores instruction files
- `documenting-code` — updates docs, including agent-facing docs
- `evolving-config` — audits agent config and shipping surfaces
- `brainstorming-ideas` — debates a plan before implementation
- `looking-up-docs` — fetches external tool, API, or platform docs

# Skill Principles

Read when the shape of a skill matters, not just its wording: invocation mode,
splits and merges, and pruning.

## Invocation fit

- Model-invoked: the agent or another skill must find it unprompted. Cost: the
  description stays loaded every session and competes with every other skill.
- User-invoked: a manual expert tool, niche reference, or router. Cost: the user
  has to remember it exists.
- A thin router that mostly delegates or restates a neighbor does not earn a
  loaded description. Fold it into the owner or make it user-invoked.

## Description

The description answers what the skill does, when to use it, and when not to.

- Lead with the action or noun the user will say.
- One trigger per branch; collapse synonym piles into one strong phrase.
- Name the neighbor skill in a NOT-for clause when misuse is likely.
- Keep body detail, examples, and rationale out of it.
- Match how users and nearby skills actually phrase the request.

## Information hierarchy

Inline in `SKILL.md`: the result, the done line, hard constraints, and rules
every run needs.

Move to `references/`, each with a read-when condition in `SKILL.md`: branch
detail, examples, long checklists, per-language or per-platform detail, and
glossary or comparison material.

Move to a target overlay only what the vendor-neutral base cannot say.

Keep definitions, rules, and caveats that belong together in one place. A weak
pointer hides must-read detail as badly as a missing one.

## Split, merge, or extend

Split when the trigger surfaces differ enough that one description would blur
routing, or when one body holds two separate workflows. Do not split for style,
small wording differences, or imagined future needs.

Prefer, in order: tighten the existing skill, move detail to references, add a
small target overlay, create a new skill.

## Prune

For each line ask: does it change behavior, does it belong here rather than in
a reference, and does another line already own this meaning? Delete generic
agent advice, repeated constraints, prose without operational effect, and stale
references to removed tools, paths, or models.