Agent authoring
Create or update this repository's agent definitions, catalog entries, routing rules, knowledge focus, workflows, runbook examples, and selector tests. Use when adding a specialist agent, changing agent authority, or keeping orchestration dispatch behavior consistent.From its SKILL.md
npx -y skills add deagy/cadre --skill agent-authoringAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.2 KB, as published. Nobody here has run it
Agent Authoring
Use this skill when an agent change must be publishable and selectable, not just a loose Markdown file.
Required changes
For each new or changed agent:
- Add or update
roster/<domain>/<agent-name>/AGENT.mdwith role, inputs, outputs, required checks, authority, escalation, and completion criteria. - Add its id to
roster/catalog-order.txt(dispatch-precedence order), if not already present. - Metadata (
phase,capability,model,codex_model,reasoning_effort,knowledge_focus) lives in the----delimited frontmatter at the top of the role'sAGENT.md(see "Frontmatter-based roles" below): update the frontmatter, then runcadre generate-role-metadatato regenerateroster/catalog.yamland routing.json'sknowledge_focusblock. Do not hand-edit those generated regions --roster/catalog.yamlandroster/orchestration/routing.json'sknowledge_focusblock are fully generated output, never an input. Note:roster/catalog.yaml's regenerated key order always exactly tracksroster/catalog-order.txt, butrouting.json'sknowledge_focusblock does not -- it never reorders an already-present role and always appends a newly-added role's entry at the very end, so don't expect a new role'sknowledge_focusentry to land near related roles there. - Update or add workflow/runbook examples when the role changes dispatch behavior.
- Add selector tests in
internal/selector's testsfor at least one representative path or keyword. - Regenerate the packaged plugin in-tree with
cadre generate-plugin --output plugin, then port the Cline presets with./bin/cadre port-cline-agents --root cline-plugins --source plugin, and commit both. The generated half ofplugin/is committed here since the monorepo merge (deagy/cadre-lifecycleis archived);validate.yml'sgenerated-contentjob re-runs the same command with--check, so source and output only advance together in one commit. - Run the orchestration test suite and confirm catalog definition paths exist. Adding a role also means bumping the expected role count in
internal/generators/package_coverage_test.go, the two count assertions ininternal/generators/cline_port_test.go, the metadata-file count ininternal/generators/frontmatter_test.go,SOURCE_ROLE_COUNT/SOURCE_SKILL_COUNTincline-plugins/cline-agents/test/presets.test.mts(a TypeScript test, so the Python suites run green without it -- only CI'scline-pluginsjob catches it), and the hand-maintained "N roles" prose inREADME.md,CLAUDE.md,roster/RUNBOOK.md,docs/role-index.md,docs/capability-index.md,.claude-plugin/marketplace.json, and.agents/skills/role-discovery/SKILL.md. Only some of those are test-enforced; the rest go stale silently. - Add a fixture to
roster/orchestration/test/fixtures/selection_golden_corpus.jsonfor each new route.test_corpus_covers_every_required_route_categoryderives its required set fromrouting.jsonitself, so a route without a fixture fails. Every catalog role must also be referenced by some route, risk rule, or team recipe —internal/orchestration/routing_health_test.goreports an unreferenced role as an orphan.
Frontmatter-based roles
Every role's AGENT.md starts with a ----delimited frontmatter block declaring id, phase, capability, model, codex_model, reasoning_effort, and knowledge_focus as flat scalar fields (see internal/generators/frontmatter.go). definition is never stored in frontmatter -- it is always derived from the file's own path under roster/. A role's metadata comes entirely from its frontmatter; there is no fallback to a legacy catalog.yaml/routing.json entry, so a missing required field fails the generator closed rather than silently inheriting a stale value. An AGENT.md that does not carry frontmatter is a generator error, not a supported transitional state. Regenerate with cadre generate-role-metadata (internal/generators/catalog_generation.go) after editing frontmatter, and validate with cadre generate-role-metadata --check.
There is no docs-only change under docs/
cadre generate-plugin copies documentation into the packaged plugin, so
editing a Markdown file that looks like pure prose still makes the generated
tree stale and fails validate.yml's generated-content job. What gets
packaged, from internal/generators/plugin_generation.go's documentation_paths:
- everything under
docs/recursively, exceptdocs/kernel/(that documents the lifecycle kernel and the LangGraph engine, whose sibling directories the package does not ship -- copying it in would produce dangling links) AGENTS.md,CONTRIBUTING.md, andIDENTITY.md
roster/ and .agents/skills/ are copied only when git-tracked, from
git ls-files. A new file that has not been git added is skipped silently,
so a packaged file edited to reference it ships pointing at something absent --
stage new files before regenerating. The documentation paths above
(AGENTS.md, CONTRIBUTING.md, IDENTITY.md, docs/) and the provider/
bundle are selected by a filesystem walk instead, so an untracked one is copied
in; there the risk is committing the packaged copy while leaving the source
untracked. Staging first makes both branches behave the same. See
roster/RUNBOOK.md §17, "Regenerating derived output", for the full sequence.
The same applies to .agents/skills/: adding or editing a skill is a
generated-content change, and a new skill also needs its
agents/openai.yaml and its .claude/skills/<name>/SKILL.md pointer, whose
name/description are compared byte-for-byte against the canonical file.
Guardrails
- Do not let an implementation agent approve its own work.
- Keep human-only decisions behind explicit gates.
- Keep role authority narrow and environment-specific.
- Prefer adding a focused specialist only when existing agents would blur accountability or miss recurring work.