agents-managers

Files (8)

• SKILL.md
• agents.md · references/
• context-management.md · references/
• debugging-agents.md · references/
• error-handling-and-recovery.md · references/
• evaluation-and-testing.md · references/
• orchestration-patterns.md · references/
• writing-agent-prompts.md · references/

SKILL.md (first lines)

<objective>
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.

Agents enable delegation of complex tasks to specialized agents that operate autonomously without user interaction, returning their final output to the main conversation.
</objective>

<quick_start>
<workflow>

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?
   - **tools**: Optional comma-separated list (inherits all if omitted)
   - **model**: Optional (`sonnet`, `opus`, `haiku`, or `inherit`)
5. Write the system prompt (the agent's instructions)
   </workflow>

<example>
```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
---

<role>
You are a senior code reviewer focused on quality, security, and best practices.
</role>

<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 be unique
</field>

<field name="description">
- Natural language description of purpose
- Include when Claude should invoke this agent
- Used for automatic agent selection
</field>

<field name="tools">
- Comma-separated list: `Read, Write, Edit, Bash, Grep`
- If omitted: inherits all tools from main thread
- Use `/agents` interface to see all available tools
</field>

<field name="model">
- `sonnet`, `opus`, `haiku`, or `inherit`
- `inherit`: uses same model as main conversation
- If omitted: defaults to configured agent model (usually sonnet)
</field>
</configuration>

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

Agents run in isolated contexts and return their final output to the main conversation. They:
- ✅ Can use tools like Read, Write, Edit, Bash, Grep, Glob
- ✅ Can access MCP servers and other non-interactive tools
- ❌ **Cannot use AskUserQuestion** or any tool requiring user interaction
- ❌ **Cannot present options or wait for user input**
- ❌ **User never sees agent's intermediate steps**

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

<workflow_design>
**Designing workflows with agents:**

Use **main chat** for:
- Gathering requirements from user (AskUserQuestion)
- Presenting options or decisions to user
- Any task requiring user confirmation/input
- Work where user needs visibility into progress

Use **agents** for:
- Research tasks (API documentation lookup, code analysis)
- Code generation based on pre-defined requirements
- Analysis and reporting (security review, test coverage)
- Context-heavy operations that don't need user interaction

**Example workflow pattern:**
```

Main Chat: Ask user for requirements (AskUserQuestion)
↓
Agent: Research API and create documentation (no user interaction)

From zuzu59/z-skills, MIT.

More from zuzu59/z-skills