If the request is not agent creation or adaptation, route through
/plugin-creator:plugin-lifecycle.
Agent Creator
Create the smallest agent definition that satisfies the requested runtime behavior.
Authority Pointers
- Activate
/plugin-creator:claude-subagent-reference for the canonical frontmatter fields,
scope rules, plugin restrictions, tool permissions, models, memory, hooks, nesting, and examples.
- Read references/agent-schema.md only for creation-specific YAML,
MCP naming, and validation constraints.
- Read references/agent-templates.md only when the request needs a
role-based supervisor contract or no similar local agent exists.
- Read references/agent-examples.md only when a concrete full-file
example is needed.
Every path, command, fact, and cross-plugin reference in the result must be available in every
target environment, bundled and reached by a relative path, or inlined. A harness variable counts
only where that harness substitutes it.
Workflow
1. Discover
Inspect agents in the requested scope and identify a similar definition before creating one. Read
the candidate completely and inventory conventions that are enforced by repository instructions.
Gate: record the target scope, destination path, nearest reusable agent or template, and any local
conventions that affect the result.
2. Resolve Requirements
Establish the agent's single responsibility, activation branches, required inputs, write boundary,
minimum tools, model needs, skill dependencies, and caller-visible output. Ask one focused question
only when a missing choice changes executable behavior.
For an orchestrated agent, require an explicit STATUS: DONE / STATUS: BLOCKED handoff and read
the role-based material in references/agent-templates.md. For a user-facing agent, adapt the
nearest local pattern and omit orchestration machinery.
Gate: every field and body step maps to a stated requirement; unresolved behavior choices block
creation.
3. Write
Start with the executable minimum and add optional fields only when required:
---
name: {agent-name}
description: '{What it does}. Use when {distinct activation branches}.'
model: {current supported alias or inherit}
tools: {minimum allowlist, when restriction is required}
---
# {Agent Title}
{Single objective.}
## Workflow
1. {Action with a checkable completion criterion.}
## Output Contract
{Exact caller-visible success and blocked forms.}
Use plain portable skill notation (/plugin-name:skill-name) and agent names
(plugin-name:agent-name) in instructions. Preserve ecosystem-owned frontmatter fields when
adapting an existing file.
Gate: the body states ordered work, a checkable completion bound, all authority pointers needed at
runtime, and the complete output contract.
4. Place
- Project:
.claude/agents/{agent-name}.md
- User:
~/.claude/agents/{agent-name}.md
- Plugin:
{plugin-root}/agents/{agent-name}.md
For plugin agents, leave plugin.json absent when default component paths are sufficient. If a
manifest exists and has no agents field, leave the field absent so default discovery continues.
If agents already exists, preserve its replacement allowlist and add the new path plus every
default-path agent that must remain loaded.
Gate: the file exists at the selected scope and plugin discovery behavior is unchanged except for
the requested agent.
5. Validate
Run:
uvx skilllint@latest check {agent-path}
For a plugin agent, also run:
claude plugin validate {plugin-root} # plugin with a manifest
claude plugin validate {plugin-root}/agents # manifestless plugin
When a manifest already has an explicit agents field, run
uv run plugins/plugin-creator/scripts/check_agent_auto_discovery.py {plugin-root}/.claude-plugin/plugin.json.
Fix every error and warning before completion. Restart the target Claude Code session after direct
on-disk agent changes so it reloads the definition.
Gate: frontmatter, plugin discovery, links, dependencies, and required tool access all pass.
Output Contract
STATUS: DONE
Agent: {name}
Path: {path}
Scope: {project, user, or plugin}
Discovery: {default path or explicit manifest path}
Authority: {references used}
Validation: {commands and exact results}
STATUS: BLOCKED
Reason: {specific missing input or failed gate}
Completed: {verified work}
Remaining: {uncompleted work}