writing-agents

To create a multi-agent definition, write a kebab-case Markdown file with YAML frontmatter. Structure the body using four sections: Purpose, Instructions, Workflow, and Report, while strictly following the five rules to enforce single-responsibility and prevent scope creep.

Use a custom agent when a task requires a distinct, single-responsibility role within a multi-agent system. Opt for a skill for shared capabilities, or orchestrator logic for workflow coordination, to avoid misuse of agent boundaries and prevent bloat.

An agent definition file requires YAML frontmatter for metadata and a body containing four specific sections: Purpose, Instructions, Workflow, and Report. Adhering to this structure ensures safety and proper validation within multi-agent systems.

Prevent scope creep in multi-agent systems by enforcing the single-responsibility principle through boundary management. Validate that each agent definition strictly adheres to the five rules and only operates within its defined Purpose and Workflow sections.

Yes, validating YAML frontmatter is a core part of creating Claude Code agents. The frontmatter guides the structure and safety of the agent, ensuring the file meets the required format before being integrated into a multi-agent system or plugin.

Compact agent definitions require strict adherence to four body sections and five rules, limiting flexibility. They should not be used when a task crosses boundaries or lacks single-responsibility, as this causes scope creep and agent boundary misuse.