> Nested instruction file for the agents/ subtree. Claude Code / Cursor IDE > and Codex CLI both load this additively when working on files in this > directory (root CLAUDE.md for the big picture, this file for local > conventions). Resolution rule: > [`../skills/_shared/inst
How to install AGENTS?
kanevry/session-orchestrator/agents
$curl -o .claude/agents/AGENTS.md https://raw.githubusercontent.com/kanevry/session-orchestrator/HEAD/agents/AGENTS.mdInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install AGENTS by running `curl -o .claude/agents/AGENTS.md https://raw.githubusercontent.com/kanevry/session-orchestrator/HEAD/agents/AGENTS.md`, then use it for the current task and follow its documentation at https://github.com/kanevry/session-orchestrator.
agents/AGENTS.md
| 1 | # `agents/` — Sub-Agent Authoring Conventions |
| 2 | |
| 3 | > Nested instruction file for the `agents/` subtree. Claude Code / Cursor IDE |
| 4 | > and Codex CLI both load this additively when working on files in this |
| 5 | > directory (root `CLAUDE.md` for the big picture, this file for local |
| 6 | > conventions). Resolution rule: |
| 7 | > [`../skills/_shared/instruction-file-resolution.md`](../skills/_shared/instruction-file-resolution.md). |
| 8 | > |
| 9 | > This is **not** an agent definition — it is the authoring spec the agent |
| 10 | > `*.md` definitions in this directory must follow. The plugin validator |
| 11 | > (`scripts/lib/validate/check-agents.mjs`) excludes `AGENTS.md` / `CLAUDE.md` |
| 12 | > from agent-frontmatter validation by name. |
| 13 | > |
| 14 | > Sibling spec: for `.claude/rules/*.md` frontmatter (conditional loading via |
| 15 | > globs/mode/host-class/expiry, plus the never-always-on invariant for |
| 16 | > auto-generated rules), see the canonical authoring spec |
| 17 | > [`docs/rule-authoring.md`](../docs/rule-authoring.md). |
| 18 | |
| 19 | ## Local Validation Commands |
| 20 | |
| 21 | Run from the plugin root. These are the scoped checks for any change under `agents/`: |
| 22 | |
| 23 | ```bash |
| 24 | node scripts/lib/validate/check-agents.mjs . # Checks 6/7/8: frontmatter, output-schema, sandbox-tier |
| 25 | npm run lint # eslint — agent .md bodies are prose, but schemas/*.json are linted |
| 26 | npm test -- tests/scripts/validate/check-agents.test.mjs tests/unit/sandbox-tier.test.mjs |
| 27 | ``` |
| 28 | |
| 29 | - **test-command:** `npm test -- tests/scripts/validate/check-agents.test.mjs` |
| 30 | - **lint-command:** `npm run lint` |
| 31 | |
| 32 | `scripts/validate-plugin.mjs` runs `check-agents.mjs` as Check 7 at plugin-distribution time, so a broken agent file fails CI fast. |
| 33 | |
| 34 | ## Frontmatter Contract |
| 35 | |
| 36 | Agent files live in `agents/` as Markdown with YAML frontmatter. Required fields: |
| 37 | |
| 38 | ```yaml |
| 39 | --- |
| 40 | name: kebab-case-name # 3-50 chars, lowercase + hyphens only |
| 41 | description: Use this agent when [conditions]. <example>Context: ... user: "..." assistant: "..." <commentary>Why this agent is appropriate</commentary></example> |
| 42 | model: inherit # inherit | sonnet | opus | haiku | fable — OR full ID like claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-sonnet-5, claude-fable-5 |
| 43 | color: blue # blue | cyan | green | yellow | purple | orange | pink | red | magenta |
| 44 | tools: Read, Grep, Glob, Bash # comma-separated string OR JSON array (both accepted; we prefer comma-string for consistency) |
| 45 | --- |
| 46 | ``` |
| 47 | |
| 48 | **Frontmatter spec source:** https://code.claude.com/docs/en/sub-agents § Supported frontmatter fields. Our local validator (`scripts/lib/validate/check-agents.mjs` + `scripts/lib/agent-frontmatter.mjs`) matches the canonical spec on `tools` (both forms accepted), `color` (canonical 8-color palette + magenta for backward-compat), and `model` (aliases + full IDs). |
| 49 | |
| 50 | **Required vs optional:** |
| 51 | - Runtime canonical doc: only `name` + `description` are required. |
| 52 | - Our validator (defensive for plugin-distribution): all four of `name + description + model + color` required; `tools` optional. |
| 53 | - `description` MUST be a single-line inline string, NOT a YAML block scalar (`>` or `|`). Put `<example>` blocks inline. |
| 54 | - `tools` accepts BOTH comma-separated string (`Read, Edit, Write`) and JSON array (`["Read", "Edit", "Write"]`). Anthropic's own reference agents use array form; we use string form for consistency. |
| 55 | |
| 56 | **Body conventions** (from Anthropic's `plugins/plugin-dev/agents/*` reference set): |
| 57 | - Sections: `**Your Core Responsibilities:**` → `**[X] Process:**` → `**Quality Standards:**` → `**Output Format:**` → `**Edge Cases:**`. |
| 58 | - Length: 500–3000 words is the recommended range. Below 500 reads as under-specified; above 3000 reads as bloated. |
| 59 | - Read-only reviewer agents: tools `Read, Grep, Glob, Bash` (no Edit/Write). Implementer agents: `Read, Edit, Write, Glob, Grep, Bash`. |
| 60 | |
| 61 | ## Model Selection & Cost Routing (#768) |
| 62 | |
| 63 | `model:` is not just a compatibility field — it is a cost/quality dial per agent. Pick deliberately, don't default to `sonnet` everywhere. |
| 64 | |
| 65 | - **`haiku`** — cheap, fast, advisory/judge roles where the task is narrow classification or a single yes/no verdict, not open-ended reasoning. Precedent: `dialectic-deriver`, `skill-applied-judge`. Pin `haiku` when the agent's whole job is "read a short input, emit a structured verdict." |
| 66 | - **`sonnet`** — the default workhorse tier. Use for implementation, test-writing, and review agents that need real reasoning over a non-trivial diff or codebase slice (code-implementer, test-writer, security-reviewer, and most of the catalog). |
| 67 | - **`inherit`** — let the coordinator/session's active model tier flow through. Default for read-only reviewer/analysis agents that benefit from running at whatever tier the operator picked for the session (e.g. an Opus session should give its reviewers Opus-quality judgment too), and for agents with no strong cost/quality reason to diverge from the session. |
| 68 | - **`opus`** — reserve for agents whose task genuinely needs the strongest available reasoning |
Related
6 picksType
- technical-directorThe Technical Director owns all high-level technical decisions including engine architecture, technology choices, performance strategy, and technical risk management.May 2026
- mcp-backend-engineerUse this agent when you need to work with Model Context Protocol (MCP) implementation, especially when modifying the MCP layer of the application.Jul 2026
- verifierPractical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit,…Jul 2026
- aegisSecurity vulnerability analysis and testingJan 2026
- agentica-agentBuild Python agents using Agentica SDK - spawn agents, implement agentic functions, multi-agent orchestrationJan 2026
- context-query-agentQuery the artifact index for precedent and guidanceJan 2026
