Skip to content

Agent Authoring

This page sums up the spec at spec/claude/agent-management/en.md (canonical source).

Status: draft

Context

The claude-shared repository collects reusable Claude Code skills and agents. An agent has two lives. The first is a source form here (agents/). The second is a runtime form in a host project (.claude/agents/ or ~/.claude/agents/). Claude Code loads the agent from the runtime form. The Agent tool then dispatches it via subagent_type.

Without a steady shape, agents drift in naming, trigger wording, tool scoping, and system-prompt quality. Reuse then turns fragile. Routing turns flaky too.

Goals and Non-Goals

Goals

  • Consistent shape on disk
  • Routable through precise, trigger-oriented descriptions
  • Least tool access needed (principle of least authority)
  • Portable across projects, no hidden dependencies
  • Clear checklist and template

Non-Goals

  • Plugin packaging
  • Downstream .claude/ configuration
  • Specific agent behavior beyond structural rules
  • Orchestration logic in the calling Claude

Requirements (excerpt)

The keywords MUST, MUST NOT, SHOULD, and MAY follow RFC 2119 (the normative-requirement rule).

Structure

  • MUST be a single Markdown file <name>.md in ASCII kebab-case
  • MUST include YAML frontmatter with name and description
  • MUST set name to match the filename without .md
  • MUST write a description that names concrete triggers ("use when …"). Don't name abstract powers
  • MUST include a system prompt in the body. Scope it to a single job and state its output shape
  • MUST keep frontmatter and system prompt in English. This keeps Claude's parsing cost low
  • MUST be self-contained: a single top-level agents/<name>.md with no sibling agents/<name>/ folder. Otherwise a recursive scan registers the nested markdown as a phantom agent

Tool access

  • MUST declare tools when restricted. Omit tools only when the agent truly needs full access
  • MUST scope tools to the minimum set required (principle of least authority)
  • MUST NOT give read-only agents write/edit/execution tools
  • SHOULD prefer dedicated tools (Read, Grep, Glob, Edit) over Bash equivalents when either would work

Model selection

  • MAY declare model (opus, sonnet, haiku)
  • SHOULD justify a pinned model in a comment or the system prompt

Locations

  • MUST place source at agents/<name>.md
  • MUST be loadable at runtime from one of three paths: .claude/agents/<name>.md, ~/.claude/agents/<name>.md, or the plugin path
  • MUST NOT assume a particular install location

Recommendations

  • SHOULD order the system prompt: role/boundaries → output format → procedure
  • SHOULD state plainly whether the agent writes code or only researches
  • SHOULD keep the system prompt under ~200 lines
  • SHOULD list positive triggers and—when overlap is likely—negative cases in description

Acceptance Criteria

  • Source file exists at agents/<name>.md with <name> in ASCII kebab-case
  • Agent dispatchable in a downstream project via subagent_type: <name>
  • Frontmatter parses as valid YAML; at minimum name and description
  • name in frontmatter == filename without .md
  • description names concrete triggers
  • If tools is set, the list is sufficient and has no unused entries
  • Read-only agents have no write/edit/execution tools
  • Agent works without claude-shared-specific context
  • No absolute paths
  • Side-effect targets and preconditions documented when applicable

Open Questions

  • Should the filename match the subagent_type string exactly?
  • Do agents need version/compatibility metadata?
  • Where's the boundary between skill and agent?
  • Should agents declare delegation targets?
  • Is there a shared reporting convention (structured vs. free-form)?

Full text

  • Canonical (EN): spec/claude/agent-management/en.md
  • Translation (DE): spec/claude/agent-management/de.md