AGENTS.md · git:20260922.2836162 · 2026-09-22 · sha256 34b67a0cd24354af
AGENTS.md git:20260922.2836162A
Immutable. This exact content never changes and is served at /api/v1/blob/34b67a0cd24354af.
# 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. ## Release/version system - Use CalVer: `YYYY.M.D` for the first release of a day and `YYYY.M.D.NN` for additional releases that day, starting at `.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.