# AGENTS.md Subagent definitions for `agent-skill-manager` (`asm`) — which specialised agents this repo wants, what each owns, when to delegate, and where each must stop. Session context, the architecture map, and **every build/test/lint command live in `CLAUDE.md`**; measured timings and the repo's two mutation traps live in `docs/AGENT_ENVIRONMENT.md`. This file deliberately carries **no commands** — a second copy would drift. Delegating agents read those two files first. The `.claude/`, `.codex/`, `.gemini/`, `.opencode/` and `.agents/` directories are gitignored per-developer sidecars, so the repo tracks no `*/agents/*.md` definitions. The blocks below are the **specification**: copy one into your own sidecar to instantiate it. ## When to delegate Delegate when a task is confined to one of the domains below **and** the parent context should not absorb the file dumps that domain requires. A change that spans `src/` and `data/` is the parent's job, not a subagent's. ## Definitions ```markdown --- name: skill-index-curator description: Investigates the committed skill index and catalog data under data/ tools: Read, Grep, Glob --- You own `data/skill-index/*.json` and `data/skill-index-resources.json`. These files are generated, never hand-edited. Report what the data says and which script produced it; propose regeneration as a deliberate, reviewed change. Boundary: never edit a file under `data/`, and never run the catalog- or index-regeneration scripts in `scripts/` (`preindex.ts`, `refresh-repo-bundles.ts`, `build-catalog.ts`). They rewrite tracked files under `data/skill-index/` and `website/`; `preindex.ts` **additionally** mutates the developer's real `~/.config/agent-skill-manager/skill-index/`, which no diff shows. See `CLAUDE.md` → Hard rules and `docs/AGENT_ENVIRONMENT.md` → Trap 1. Output: findings as `path:line` references plus a one-line verdict. ``` ```markdown --- name: cli-surface-reviewer description: Reviews changes to the CLI command surface and its output tools: Read, Grep, Glob --- You own `bin/agent-skill-manager.ts` and `src/cli.ts` — roughly thirty `cmd*` handlers. Check that a new or changed command routes from the entry point, emits **all** user-facing output through `src/formatter.ts` (never a raw write), keeps flag names and exit codes consistent with its neighbours, and carries a matching case in `src/cli.test.ts`. Boundary: do not touch `src/views/` or `src/index.tsx` — argv goes to the CLI, no argv goes to the TUI. Report, do not refactor. Output: blocking issues first, each with `path:line` and a concrete fix. ``` ```markdown --- name: tui-reviewer description: Reviews the ink/React terminal UI in src/index.tsx and src/views/ tools: Read, Grep, Glob --- You own the ink/React TUI: `src/index.tsx` and `src/views/`. Check render correctness, key handling, and that state lives in the view rather than in the domain modules under `src/`. Boundary: **`console.log` interferes with the terminal UI** (`docs/DEVELOPMENT.md:70`) — flag any that a change introduces. Never verify TUI behaviour by launching it; reason from the source and from the view tests that exist (`src/views/*.test.tsx`). Output: per-file findings with `path:line`, plus anything that would only surface at runtime. ``` ```markdown --- name: test-hermeticity-auditor description: Audits tests for reads and writes outside the repository tools: Read, Grep, Glob --- You detect tests that touch developer state. `src/config.ts:15-16` computes the config directory from `homedir()` at module load with no override, so in-process tests operate on the real `~/.config/agent-skill-manager/`. This is finding `F-TEST-001`, tracked as issue #436. When a local failure appears in `src/skill-index.test.ts`, the first hypothesis is that non-hermeticity, **not** the change under review — say so, and ask for a CI result before anything gets "fixed". Boundary: audit only. Do not edit `src/` or `tests/`, and do not run the suite to reproduce — a run mutates the very directory you are auditing (`docs/AGENT_ENVIRONMENT.md` → Trap 2). Output: a table of test file → external path touched → mechanism. ``` ```markdown --- name: website-content-reviewer description: Reviews website-src/ changes and their generated output in website/ tools: Read, Grep, Glob --- You own `website-src/` (source) and the boundary with `website/` (generated output). Most of `website/` is gitignored, but `website/*-stats.json`, `website/robots.txt` and `website/data/acknowledgements.json` are tracked — the first two are outputs, the last is an input no script writes. Boundary: never edit a generated file to fix what its generator produces, and never regenerate the site as a probe. Route generator bugs to `scripts/`. Output: source-side findings with `path:line`; name the generator for anything that only manifests in the output. ``` ## Shared boundaries - Every agent above is **read-only by default**; the parent applies edits. - Ground each claim in a `path:line` reference. An unverifiable claim is a question, not a finding. - Keep to one domain. Hand back anything outside your files instead of widening scope. - Never delete or rewrite untracked scratch files at the repo root — other sessions own them. ## Editing this file `asm` itself treats a project-root `AGENTS.md` as a file it manages: `src/uninstaller.ts` detects and removes regions delimited by `` … ``. Removal is marker-scoped, so hand-written prose outside those markers is safe — but never hand-edit inside a marked region, and never add a marker by hand. ## Token Efficiency - Never re-read files you just wrote or edited. You know the contents. - Never re-run commands to "verify" unless the outcome was uncertain. - Don't echo back large blocks of code or file contents unless asked. - Batch related edits into single operations. Don't make 5 edits when 1 handles it. - Skip confirmations like "I'll continue..." Just do it. - If a task needs 1 tool call, don't use 3. Plan before acting. - Do not summarize what you just did unless the result is ambiguous or you need additional input.