AGENTS

Name: AGENTS
Author: Kanevry

47stars8forks

How to install AGENTS?

kanevry/session-orchestrator/agents

$curl -o .claude/agents/AGENTS.md https://raw.githubusercontent.com/Kanevry/session-orchestrator/HEAD/agents/AGENTS.md

Installs into the current project.

Summary

> 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

Files · 1

View on GitHub

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

People who liked this also viewed

6 picks

Type

AGENTS

47stars8forks

View on GitHub

How to install AGENTS?

kanevry/session-orchestrator/agents

$curl -o .claude/agents/AGENTS.md https://raw.githubusercontent.com/Kanevry/session-orchestrator/HEAD/agents/AGENTS.md

Installs into the current project.

Summary

Files · 1

View on GitHub

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

People who liked this also viewed

6 picks

Type