Skip to content

Last updated

Sub-agent rules skill

The single source of standing rules for every sub-agent that works a quest: memory access, tracker calls, test-first, versioning, the public site, git, the one-line output and model tiers. Each agent definition preloads it, so the orchestrator never pastes rule files into a dispatch prompt. This is a filtered copy of the skill I use in Kamari: project-specific values (ids, paths, scripts, file names) are replaced with [BRACKETED] placeholders or removed. It is not user-invocable; agents load it themselves.


name: quest description: Standing rules for every sub-agent working a quest (memory, quest MCP calls, tests, versioning, public site, git, output line, model tiers). user-invocable: false disable-model-invocation: false


Sub-agent rules (single source)

Standing rules; the project's agents get them preloaded, so a dispatch prompt only needs the quest id and any delta. Global rules: ~/.claude/CLAUDE.md; repo rules: CLAUDE.md; map: LLM.md. Always read LLM.md, [SECURITY RULES FILE] and [TESTING RULES FILE], plus the subsystem files your quest's Extra: paths map to (index table in LLM.md).

Memory

  • Never call memory_list WITHOUT a filter (the bare listing overflows). Fetch named items with memory_list keys=["[PROJECT]:quest-workflow", ...] and check missing, or list compactly with memory_list key_prefix=["[PROJECT]:", "convention:"] compact=true limit=200 (page with next_offset). A reply without a total key means an old server ignored the filters; do not trust it. Or use memory_get on a known id. The public-site rule lives only in this file (section "Public site" below).
  • Only the main session writes memory. Never change a memory item.

Quest MCP calls

  • Every write needs identity (model plus agent name, e.g. "claude-sonnet sub-agent ").
  • quest_add_update takes message. Text over max_log_len (3000 chars) is REFUSED, not cut: keep each update shorter, or attach the long part with file_name + file_content_b64. Keep base64/binary payloads tiny: a large one overflows the 64k output limit.
  • quest_update_status takes new_status; closing also needs commit_hash. Set WIP when you start, log progress.
  • Hand tests: for EVERY hand test or owner action you report, quest_checklist_add with actor="human" and how_to (one line), then move the quest to Needs human, never only an update. Closed is refused while a human item is open. Blocked is for external dependencies.
  • Project artifacts (quests, commits, the public site, docs) never name another of the user's projects; describe it generically.

Process

  • Test first: write the guard test, show it failing, then write the code.
  • Tests are immutable without explicit permission, except this standing rule (user, 2026-10-30): once the user has EXPLICITLY decided to change a behaviour (decision recorded on the quest), you may update existing tests whose only problem is that they pin the OLD behaviour. (1) The test must assert exactly the behaviour the decision replaces; no other test edits. (2) List every such edit (file::test_name, old vs new expectation) in a quest update AND in your report. (3) Prefer updating the assertion over deleting the test. (4) Never weaken a test to make unrelated code pass, and never use this for flakes or refactors.
  • Design questions: first find the standard (cite the RFC or spec where one applies), name it and recommend the conforming option, record it on the quest.
  • Versioning: bump in the same commit as the code. A core change bumps the package version; a plugin change bumps its own manifest. PATCH for routine fixes, MINOR when a contract changes (new capability or tool, schema fields, noticeable behaviour). Test-only, CSS, README and template changes need no bump. Re-read the version file right before bumping.
  • Public site: keep the public site updated in the same commit as the quest (user, 2026-10-31). The CHANGELOG holds ONLY what an average user cares about: new features, settings, visible behaviour, security in plain terms; if in doubt leave it out. Entry: newest first, ASCII, 60 words or fewer, unique title, no quest ids, hashes or source file names. Pages: fix any claim your change makes false, verified against code. Both rules are enforced by tests.

Tests

  • One test run at a time on this box (all sessions, all repos). Never kill another's run.
  • Before closing: [CHECKS SCRIPT] (lint, typecheck, full suite; it takes the machine-wide lock itself).
  • Targeted runs go through [TEST LOCK WRAPPER] -m pytest <path>.
  • Known load-sensitive flakes are listed in one place in the test configuration. If only one of them fails, re-run it alone and do not edit it.

Git

  • Commit message: at most 2 sentences referencing the quest id, then a blank line and the trailer Co-Authored-By: Claude <Model Name> <noreply@anthropic.com> naming your own model.
  • Stage explicit paths only. Never commit quest files. Push to origin main, then close the quest with the commit hash.
  • Concurrent quests on branches: rebase onto main, rerun checks, fast-forward only (no merge commits), in the landing order fixed at dispatch.

Never

  • No push notifications. Never deploy. Never change the live server.
  • A decision that belongs to the user: write the question on the quest, set it Blocked with a note, and report it. Do not guess.

Output

Exactly one line: <quest_id>: <status>. If not Closed, add why (or the question). If Closed, add the commit hash.

Model tiers (check your own routing)

Tier Work
haiku Docs-only or prose fixes, typos, formatting, moving files with no logic change
sonnet Normal feature and bug work with tests, templates, CSS, read-only tools
opus Anything that deploys, deletes or syncs live data, credentials and secrets, publish or scrub gates, authentication and permissions, git history rewrites

The opus path floor wins; when unsure go up a tier. If you find the quest needs a higher tier than you were given, stop and report it.

---
name: quest
description: Standing rules for every sub-agent working a quest (memory, quest MCP calls, tests, versioning, public site, git, output line, model tiers).
user-invocable: false
disable-model-invocation: false
---
# Sub-agent rules (single source)

Standing rules; the project's agents get them preloaded, so a dispatch prompt only
needs the quest id and any delta. Global rules: `~/.claude/CLAUDE.md`; repo rules: `CLAUDE.md`; map: `LLM.md`.
Always read `LLM.md`, [SECURITY RULES FILE] and [TESTING RULES FILE], plus the subsystem
files your quest's `Extra:` paths map to (index table in `LLM.md`).

## Memory
- Never call `memory_list` WITHOUT a filter (the bare listing overflows).
  Fetch named items with `memory_list keys=["[PROJECT]:quest-workflow", ...]`
  and check `missing`, or list compactly with
  `memory_list key_prefix=["[PROJECT]:", "convention:"] compact=true limit=200`
  (page with `next_offset`). A reply without a `total` key means an old server
  ignored the filters; do not trust it. Or use `memory_get` on a known id.
  The public-site rule lives only in this file (section "Public site" below).
- Only the main session writes memory. Never change a memory item.

## Quest MCP calls
- Every write needs `identity` (model plus agent name, e.g. "claude-sonnet sub-agent <quest_id>").
- `quest_add_update` takes `message`. Text over `max_log_len` (3000 chars)
  is REFUSED, not cut: keep each update shorter, or attach the long part with
  `file_name` + `file_content_b64`. Keep base64/binary payloads tiny: a large
  one overflows the 64k output limit.
- `quest_update_status` takes `new_status`; closing also needs `commit_hash`. Set WIP when you start, log progress.
- Hand tests: for EVERY hand test or owner action you report, `quest_checklist_add` with
  `actor="human"` and `how_to` (one line), then move the quest to `Needs human`, never only an update.
  Closed is refused while a human item is open. `Blocked` is for external dependencies.
- Project artifacts (quests, commits, the public site, docs) never name another of the
  user's projects; describe it generically.

## Process
- Test first: write the guard test, show it failing, then write the code.
- Tests are immutable without explicit permission, except this standing
  rule (user, 2026-10-30): once the user has EXPLICITLY decided to change a
  behaviour (decision recorded on the quest), you may update existing tests
  whose only problem is that they pin the OLD behaviour. (1) The test must
  assert exactly the behaviour the decision replaces; no other test edits.
  (2) List every such edit (file::test_name, old vs new expectation) in a
  quest update AND in your report. (3) Prefer updating the assertion over
  deleting the test. (4) Never weaken a test to make unrelated code pass,
  and never use this for flakes or refactors.
- Design questions: first find the standard (cite the RFC or spec where one
  applies), name it and recommend the conforming option, record it on the
  quest.
- Versioning: bump in the same commit as the code. A core change bumps the
  package version; a plugin change bumps its own manifest. PATCH for routine
  fixes, MINOR when a contract changes (new capability or tool, schema fields,
  noticeable behaviour). Test-only, CSS, README and template changes need no
  bump. Re-read the version file right before bumping.
- Public site: keep the public site updated in the same commit as the quest
  (user, 2026-10-31). The CHANGELOG holds ONLY what an average user cares
  about: new features, settings, visible behaviour, security in plain terms;
  if in doubt leave it out. Entry: newest first, ASCII, 60 words or fewer,
  unique title, no quest ids, hashes or source file names. Pages: fix any
  claim your change makes false, verified against code. Both rules are
  enforced by tests.

## Tests
- One test run at a time on this box (all sessions, all repos). Never kill another's run.
- Before closing: [CHECKS SCRIPT] (lint, typecheck, full suite; it takes
  the machine-wide lock itself).
- Targeted runs go through [TEST LOCK WRAPPER] `-m pytest <path>`.
- Known load-sensitive flakes are listed in one place in the test
  configuration. If only one of them fails, re-run it alone and do not edit it.

## Git
- Commit message: at most 2 sentences referencing the quest id, then a blank
  line and the trailer
  `Co-Authored-By: Claude <Model Name> <noreply@anthropic.com>`
  naming your own model.
- Stage explicit paths only. Never commit quest files. Push to origin main,
  then close the quest with the commit hash.
- Concurrent quests on branches: rebase onto main, rerun checks, fast-forward
  only (no merge commits), in the landing order fixed at dispatch.

## Never
- No push notifications. Never deploy. Never change the live server.
- A decision that belongs to the user: write the question on the quest, set
  it Blocked with a note, and report it. Do not guess.

## Output
Exactly one line: `<quest_id>: <status>`. If not Closed, add why (or the
question). If Closed, add the commit hash.

## Model tiers (check your own routing)
| Tier | Work |
|---|---|
| haiku | Docs-only or prose fixes, typos, formatting, moving files with no logic change |
| sonnet | Normal feature and bug work with tests, templates, CSS, read-only tools |
| opus | Anything that deploys, deletes or syncs live data, credentials and secrets, publish or scrub gates, authentication and permissions, git history rewrites |

The opus path floor wins; when unsure go up a tier. If you find the quest
needs a higher tier than you were given, stop and report it.