creating-custom-agents

Create a `.agent.md` file with frontmatter defining name, description, model, and tools, followed by a role section, default workflow, constraints, and output expectations. Keep the toolset minimal and delegate reusable procedures to skills rather than embedding them in the agent body.

Choose an agent when the work needs a persistent role, a specific tool profile, or a distinct collaboration pattern. Use a prompt for a reusable task starter and a skill for procedural knowledge that multiple agents or users might share.

Grant only the tools the role genuinely needs, such as search, read, think, or todo for a review-focused agent. Avoid blanket tool access, since oversized tool arrays are a common failure mode that dilutes the agent's focus.

Agents become bloated when given vague missions like helping with everything, when detailed workflow instructions are embedded instead of delegated to skills, or when repository-wide instructions are copied into the agent file. Tighten the role boundary and move procedures out.

A single agent should not absorb an entire multi-stage workflow. For orchestration scenarios, define specialist agents with clear boundaries and let an orchestrator delegate to them, referencing prompts and skills for entrypoints and procedures.