skills

# AGENTS.md

Instructions for AI agents (Claude Code, etc.) working in this repo.

## When adding, renaming, or removing a skill

1. **Update `README.md`** — keep the "Skills" list in sync. Each entry links to the skill's `SKILL.md` and summarises what it covers. If you add a skill and don't update the README, the change is incomplete.
2. **Add evaluation coverage** — add the new skill to the relevant evaluation suite, with direct, novel, and no-change cases that exercise its expected behavior and restraint. Keep those cases in `evals/`, with deterministic validation where applicable; runtime `SKILL.md` files do not carry RED/GREEN scenario sections. A new skill is incomplete without evaluation coverage.
3. **Do not update plugin or skill versions unless explicitly asked.** If the user asks for a release/version bump, use the release system below.

## Skill authoring checklist

Before considering any skill addition or edit complete, verify:

1. The frontmatter description starts with `Use when` and contains concrete trigger conditions only.
2. The body states one core principle and gives ordered, imperative steps.
3. Tables support rather than replace the procedure; failed checks specify the next action, and the procedure has an explicit finish gate.
4. Examples are minimal and behavior-preserving; exceptions and non-applicable cases are explicit.
5. The evaluation corpus includes direct, novel, and no-change coverage, including a counterexample against over-application.
6. README and router integration are updated where applicable, `npm run lint` passes, and versions remain unchanged unless requested.

## Evaluation result documentation

- Keep the result tables in `README.md` and `evals/README.md` synchronized. Each
  cell shows the latest available result for that skill and metric.
- Replace superseded values in place. Do not turn either README into a journal
  of dated runs, targeted rechecks, repair history, or per-run commentary.
- Keep detailed scorecards, audit decisions, run provenance, and historical
  evidence in evaluation artifacts and the change record, not in the READMEs.
- Update only metrics supported by the latest evidence; leave unrelated skill
  results unchanged.

## Evaluation runs

- Routine tasks may add or update evaluation coverage and run deterministic
  checks, but must not execute live model evaluations unless the task explicitly
  requests them. `npm run lint`, `npm run evals:validate`, and `npm test` do not
  make live model calls.
- For pre-release live evaluations, follow the manual checklist in `README.md`.

## Release/version system

- Use CalVer: `YYYY.M.D` for the first release of a day and `YYYY.M.D.N` or
  `YYYY.M.D.NN` for additional releases that day. Daily release numbers range
  from `.1` to `.99`; single-digit values are normalized to a zero-padded form,
  so `.1` and `.01` both resolve to `.01`.
- Do not zero-pad month or day values. Use `2026.6.17`, not `2026.06.17`.
- Keep root `plugin.json`, `.claude-plugin/plugin.json`, and `.codex-plugin/plugin.json` on the same version.
- New Git release tags should match the manifest version exactly.
- Existing zero-padded tags from before this policy map to the non-padded manifest version. For example, origin tag `2026.06.16` maps to manifest version `2026.6.16`.
- Only cut a release when publishing installable changes. Skill wording/fixes, new skills/triggers, removals, and renames all use the publication date as the version.
- Call out removals and renames clearly in release notes because they break existing user references.

## Skill layout

- Skills live at `skills/<skill-name>/SKILL.md`. **Flat** — never nest by language or topic. Encode the topic in the directory name instead (e.g. `kotlin-structured-concurrency`, not `kotlin/structured-concurrency`).
- The `name:` in the SKILL.md frontmatter **must match the directory name** exactly.
- Use lowercase kebab-case for directory and `name:` values.

## Manifests

- Root `plugin.json`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `.agents/plugins/marketplace.json`, and `.codex-plugin/plugin.json` are all JSON (not JSONC). Validate with `jq . <file>` before committing.
- Root `plugin.json` targets Agent Plugins v1.0.0 and contains only portable schema fields. Keep client-specific fields in the client manifests.
- The plugin `name` field in all three manifests must stay `chrisbanes-skills`.

## Commits and PRs

- Do not add AI attribution to commits or PRs — no `Co-Authored-By`, `Generated by`, or similar lines.

## What not to do

- Don't add CI, repository-wide build tooling, or standalone scripts unless
  asked. Skill-local scripts are allowed when they are part of an explicitly
  requested skill and provide deterministic behavior; test them.
- Don't reorganise existing skills "for consistency" without a concrete reason; renames break user references.