agents-managers

name	agents-managers
description	Expert guidance for creating, building, and orchestrating Claude Code agents. Use when creating agents, writing system prompts, configuring tool access, using the Task tool, or setting up multi-agent workflows with background execution.
license	MIT
metadata	{"maintainer":"izo"}

Agents are specialized Claude instances that run in isolated contexts with focused roles and limited tool access. This skill teaches you how to create effective agents, write strong system prompts, configure tool access, and orchestrate multi-agent workflows using the Task tool.

<quick_start>

1. Run /agents command
2. Select "Create New Agent"
3. Choose project-level (.claude/agents/) or user-level (~/.claude/agents/)
4. Define the agent:
   • name: lowercase-with-hyphens
   • description: When should this agent be used? (50–300 chars, front-load trigger words)
   • tools: Optional space-separated list (inherits all if omitted)
   • model: Optional (sonnet, opus, haiku, or inherit)
5. Write the system prompt using pure XML tags

```markdown --- name: code-reviewer description: Expert code reviewer. Use proactively after code changes to review for quality, security, and best practices. tools: Read Grep Glob Bash model: sonnet --- You are a senior code reviewer focused on quality, security, and best practices.

<focus_areas>

• Code quality and maintainability
• Security vulnerabilities
• Performance issues
• Best practices adherence </focus_areas>

<output_format> Provide specific, actionable feedback with file:line references. </output_format>

</example>
</quick_start>

<file_structure>
| Type | Location | Scope | Priority |
|------|----------|-------|----------|
| **Project** | `.claude/agents/` | Current project only | Highest |
| **User** | `~/.claude/agents/` | All projects | Lower |
| **Plugin** | Plugin's `agents/` dir | All projects | Lowest |

Project-level agents override user-level when names conflict.
</file_structure>

<configuration>
<field name="name">
Lowercase letters and hyphens only. Must match the filename (without `.md`).
</field>

<field name="description">
50–300 characters. Front-load trigger words ("Use when…", "Review code for…").
Used for automatic agent selection — this is the most important field.
</field>

<field name="tools">
Space-separated list: `Read Write Edit Bash Grep`
Omit to inherit all tools. Use least privilege: give only what the agent needs.
</field>

<field name="model">
`sonnet`, `opus`, `haiku`, or `inherit`. Omit to use the configured default.
- `opus` — orchestration, complex multi-file analysis, architecture decisions
- `sonnet` — focused tasks, audits, automation
- `haiku` — fast read-only diagnostics, structured output
</field>
</configuration>

<execution_model>
<critical_constraint>
**Agents are black boxes that cannot interact with users.**

Agents return their final output to the main conversation. They:
- ✅ Can use tools: Read, Write, Edit, Bash, Grep, Glob
- ✅ Can access MCP servers and non-interactive tools
- ❌ Cannot use AskUserQuestion or any tool requiring user interaction
- ❌ User never sees agent's intermediate steps

The main conversation sees only the agent's final report.
</critical_constraint>

<workflow_design>
Use **main chat** for:
- Gathering requirements from user (AskUserQuestion)
- Presenting options or decisions
- Any task requiring user confirmation

Use **agents** for:
- Research (API docs lookup, code analysis)
- Code generation from pre-defined requirements
- Analysis and reporting (security review, test coverage)
- Context-heavy operations with no user interaction needed

**Pattern:**

Main Chat: Ask user for requirements ↓ Agent: Research and create implementation plan ↓ Main Chat: Review plan with user, confirm approach ↓ Agent: Generate code ↓ Main Chat: Present results

</workflow_design>
</execution_model>

<system_prompt_guidelines>
<principle name="use_pure_xml_structure">
Structure the system prompt with pure XML tags. Remove ALL markdown headings (##, ###) from the body.

```markdown
---
name: security-reviewer
description: Reviews code for OWASP security vulnerabilities. Use when auditing auth, input handling, or data exposure.
tools: Read Grep Glob Bash
model: sonnet
---

<role>
You are a security reviewer specializing in OWASP Top 10.
</role>

<focus_areas>
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization issues
- Sensitive data exposure
</focus_areas>

<workflow>
1. Read the modified files
2. Identify security risks with file:line references
3. Rate severity (Critical/High/Medium/Low)
4. Provide specific remediation steps
</workflow>

Keep markdown formatting WITHIN content (bold, italic, lists, code blocks). Use XML for structure only.

Tailor instructions to the specific task domain.

❌ Bad: "You are a helpful assistant that helps with code" ✅ Good: "You are a React component specialist. Analyze hooks best practices, performance anti-patterns, and accessibility."

<intelligence_rules> Simple agents (single task): role + constraints + workflow minimum. Medium agents (multi-step): add workflow steps, output_format, success_criteria. Complex agents (research + generation + validation): add all relevant tags including validation and examples. </intelligence_rules> </system_prompt_guidelines>

<background_execution> Agents can run in the background using run_in_background: true, enabling parallel execution.

<parallel_agents> Launch multiple independent agents simultaneously in a single message:

Task 1: description="Review code quality", subagent_type="code-reviewer", run_in_background=true
Task 2: description="Run security scan", subagent_type="security-scanner", run_in_background=true
Task 3: description="Check test coverage", subagent_type="test-analyzer", run_in_background=true

Then retrieve all results with TaskOutput. </parallel_agents>

<when_to_use_background> Use background for:

• Long-running analysis (security review, comprehensive code analysis)
• Multiple independent tasks runnable in parallel
• Research tasks that may take significant time

Don't use background for:

• Quick operations (< 10 seconds)
• Tasks that depend on each other sequentially
• Simple single-file operations </when_to_use_background> </background_execution>

<ulk_extensions> When creating agents for the ulk framework (framework/agents/), apply these additional rules on top of the standard conventions above.

Required frontmatter fields:

---
name: agent-name
type: custom-command
description: <Verb> <what> — <details>. Use for '<trigger1>' / '<trigger2>'. Not for <exclusion>.
tools: Read, Glob, Grep, Bash, Write, Task
model: opus | sonnet | haiku
phase: define | plan | build | verify | review | ship | orchestrator
invocation: /ulk:name or "trigger phrase"
---

Optional ulk fields:

• durability: amplifier|compensatory|mixed — amplifier = gains value as models improve; compensatory = compensates a current model limit (requires sunset_when:); mixed = both
• sunset_when: "<condition>" — required if durability: compensatory — the condition that makes this agent obsolete
• effort: xhigh|low — override session effort level (xhigh for opus orchestrators, low for haiku diagnostics)
• refuses: ["bash:git push --force*", "edit:.env*"] — patterns blocked by the refusal-scope hook
• permissions: read-only | scoped-write | full — write scope (read-only blocks all Edit/Write)
• extends: [_shared/base-rules.md, ...] — document which shared protocols this agent applies

Numbering (v7+): IDs 80–99 are the active range. Run generate-registry.cjs to auto-assign — never hardcode.

Golden test (mandatory): Create framework/tests/agents/<name>.golden.md at the same time as the agent file. This defines structural invariants (frontmatter fields, required sections, forbidden patterns) that the CI regression suite checks.

Model policy:

• haiku — read-only diagnostics with structured output (godspeed, gandalf)
• opus — orchestrators, complex multi-file analysis, architecture
• sonnet — everything else

Description quality: Run python3 framework/tools/description-audit.py to score agent descriptions (target ≥ 7/10).

Roster governance: A new agent can only enter if an existing one exits (archival), or if real usage (ulk agents stats) proves a gap. Extend an existing agent with a new mode before creating a new agent. </ulk_extensions>

<success_criteria> A well-configured agent has:

• Valid YAML frontmatter (name matches file, description includes triggers)
• Clear role definition with XML structure
• Appropriate tool restrictions (least privilege)
• Description field optimized for automatic routing (50–300 chars, front-loaded)
• Model selection appropriate for task complexity
• Successfully tested on representative tasks
• (ulk) Golden test file created in framework/tests/agents/ </success_criteria>