[joshunrau]

The repo carried 39 agent skills (12,754 lines). Most were third-party generics that duplicate each other or contradict repo rules. Every odc-* domain skill restated its playbook, often sentence for sentence. This PR cuts the skills to 8 (654 lines), cuts .agents/docs from 2,955 to 1,449 lines, and fixes the stale facts that turned up along the way. No code, config or tests change.

Where facts live now: the root AGENTS.md routes. A playbook holds a task's steps and traps. A workspace AGENTS.md holds that workspace's conventions. An architecture doc holds a mechanism that spans workspaces. A skill survives only if it has no natural home in one of those and benefits from auto-triggering. Every unique fact from a deleted skill was moved to its home, not dropped.

Skills deleted: third-party (21 of 24)

Pinned in skills-lock.json, so the only choices were keep or delete. Edits would be clobbered on update. Anyone who wants one can install it user-level.

Skill	Why it went
grilling, grill-me, grill-with-docs, batch-grill-me, loop-me, to-questionnaire	Six of seven "interview the user" variants. interview stays because it is a superset of grilling: the same text plus a calibration step and a "question stays open until decided" rule. grill-me is a one-line alias. batch-grill-me, loop-me and to-questionnaire are marked in-progress upstream. grill-with-docs writes CONTEXT.md and docs/adr/, which this repo does not use: there is no ADR flow, and docs/ is the user manual. loop-me and to-questionnaire write personal workflow files into the repo root.
handoff	A personal session habit that writes to the OS temp dir. Nothing repo-specific.
implement	Its close-out skips root "Before you are done" and commits straight to the current branch.
request-refactor-plan	Deprecated upstream. Files issues without the labels opening-issues requires.
research	Its one repo-specific step is to save notes as Markdown in the repo, which makes a second copy of facts that already have a home.
systematic-debugging (1,300 lines)	Duplicates diagnosing-bugs, the one debugging method kept. About 360 lines are the author's own skill-test fixtures. It references superpowers:* skills that are not installed, and its "validate at every layer" contradicts "validate at the boundary, trust inside".
tdd	Calls the repo's standard unit-test pattern bad: mocking our own services with MockFactory and asserting on their calls. Its "test only at agreed seams" conflicts with unit + e2e at 100% coverage.
code-review	Depends on /setup-matt-pocock-skills and docs/agents/issue-tracker.md, neither of which exists. It triggers on "review a PR", competing with review-pr.
codebase-design, design-an-interface, improve-codebase-architecture, domain-modeling	Four overlapping architecture skills. Their vocabulary bans "service", "component" and "API", which are NestJS/React terms here. They depend on CONTEXT.md/docs/adr/, which don't exist. design-an-interface is deprecated upstream.
writing-great-skills	Generic advice on writing skills. odc-agent-docs is the house format.
find-skills	Installs third-party skills from a registry, and triggers on any "how do I do X" question.
frontend-design	"Take one real aesthetic risk" and "invent a palette" contradict apps/web/AGENTS.md's libui semantic tokens.
vercel-react-best-practices (7,900 lines)	Mostly Next.js, RSC and server actions, none of which is used here. It prescribes SWR, but apps/web uses TanStack Query. It suggests adding better-all, which breaks the no-new-deps rule. It flags index.ts barrels, which apps/web requires. Its AGENTS.md repeats its rules/ word for word.

Kept: interview, diagnosing-bugs and agent-browser. diagnosing-bugs ends by handing off to /improve-codebase-architecture, which is now gone. Since the skill is third-party it is left unedited, and the agent just reports the finding.

Skills deleted: first-party (10)

Skill	Why it went
odc-commit	Its trailer rule, Co-Authored-By: <model> with no email, conflicts with the trailer the agent harness appends. Its Conventional Commits and scope rules already sit in root AGENTS.md hard rules and CONTRIBUTING.md.
odc-open-pr	Its attribution block only collected odc-commit's trailers. "Branch first" is in CONTRIBUTING.md. Its one fact that holds for every contributor, that PRs and issues target DouglasNeuroInformatics/OpenDataCapture main, is now a root hard-rule bullet.
odc-orientation	Never auto-loaded (disable-model-invocation). Its reading order restated root, and each of its "three landmines" is stated by its owning doc. Its hand-kept index of skills duplicated the harness's own list and had gone stale. Root now has a one-line "New here?" pointer.
odc-api, odc-release, odc-run-locally, odc-web-route, odc-frontend, odc-testing, odc-instruments	Each restated its playbook(s). Unique facts were folded in: • currentUser: RequestUser forwarding → apps/api/AGENTS.md • release recovery → cut-a-release.md §Recover • the exact runtime/v1/dist ENOENT → run-locally.md • route-tree.ts rewritten by every Vite run → add-web-route.md • jsx-no-literals ignoreProps blind spot → apps/web/AGENTS.md • vitest list --filesOnly proof → testing-strategy.md • new-field-kind 422 trap → runtime-core/AGENTS.md • vendor literal-version exception → vendor/AGENTS.md Several of these skills were also wrong: • "no playground image ships" (it does) • gateway and instrument-library "have no vitest project" (both do) • gateway "does not localize zod messages" (it does) • odc-web-route's "one key, two callers" example no longer exists

Skills kept

Skill	Change
odc-debugging	94 → 52. One line per symptom. Every row points at the doc that owns the fix, never at a skill.
odc-done	109 → 37. Cut what restated root "Before you are done". Kept the checks a green run does not prove.
odc-agent-docs	135 → 69. Cut the narrative and the duty to maintain the deleted skill index, and removed an exception for a deleted skill's AGENTS.md.
review-pr	Fixed: it fetched refs/pull/* from origin, which is a fork and has none. It no longer hard-codes a GitHub username.
opening-issues	Unchanged. Its label table matches gh label list.
interview, diagnosing-bugs, agent-browser	Third-party, unchanged.

Other docs

• .rules deleted. Zed reads only the first match among .rules … AGENTS.md, CLAUDE.md, so this 7-bullet file was hiding root AGENTS.md from Zed users. Five bullets were root hard rules. The other two ("never generate scripts to make changes" and "minimal text outside code blocks") are personal preferences.
• .agents/docs/packages/: 11 per-package files merged into index.md, one row each (717 → 34 lines). Each file's unique content was one "reach for this when…" line. The rest were hand-copied API listings that had drifted: libnest.md listed ValidationSchema as used, though nothing imports it, and libui-form-types.md had the wrong version pins.
• workspace-map.md (150 → 74 lines). Kept: the dependency graph (recomputed from every package.json), built vs source-only, published, and the vitest glob trap. Cut: what each workspace AGENTS.md already says. Fixed: a stale release version, and a missing playground-url consumer.
• Architecture docs:
  • auth-and-permissions (244 → 137): the route table claimed to be a "full inventory" but was missing routes. It now lists only the unusual declarations, plus a grep. The AuditLogger usage claim was stale.
  • instrument-pipeline (229 → 134): named the wrong validate: true caller.
  • runtime-and-vendor (200 → 58): its per-workspace sections restated each AGENTS.md, and it gave two different tsconfig counts.
  • testing-strategy (197 → 131).
• Playbooks: all 12 kept, and each is shorter even after absorbing the skill facts. Fixes:
  • add-e2e-test: a wrong pageModels key.
  • add-env-var: a gateway config.ts step, which had never been documented.
  • add-vitest-project: four stale claims.
• Root AGENTS.md:
  • Added the "PRs and issues go to upstream main" bullet.
  • Replaced the odc-orientation pointer.
  • Dropped the "Blog posts" row, which duplicated the playbooks table.

For the maintainer, not changed here

• Root's hard rule "never run the apps/web route-tree generator" sits awkwardly beside "Before you are done": pnpm test:e2e (and pnpm dev/pnpm build) rewrite route-tree.ts as a side effect. add-web-route.md documents how to work around it (revert the diff). Whether the rule's wording should say so is your call.
• Possible latent bug, spotted while checking auth-and-permissions.md: apps/api/src/subjects/subjects.service.ts:123 spreads ...accessibleQuery(ability, 'create', 'Subject') into the arguments of createMany. Worth a separate look.

Verification

• A script checked every .agents/docs/… and .agents/skills/… path and #anchor referenced anywhere in the repo. All resolve. Two anchors into deleted sections were repointed: runtime-internal and runtime-meta AGENTS.md.
• Facts moved into workspace AGENTS.md files were spot-checked against the code: ignoreProps: true, catalog:react19, Success!, currentUser: RequestUser, .exhaustive().
• Prettier ran on every changed file, and the commit hooks passed.
• skills-lock.json and the .claude/skills symlinks match the 8 remaining skills.
• pnpm lint, pnpm test:coverage and pnpm test:e2e were not run: the change touches only Markdown, skills-lock.json and symlinks, none of which a lint, test or e2e run reads.

🤖 Generated with Claude Code