Agent Design

Agent Design Guide

Required Frontmatter Fields

| Field | Format | Rules | |-------|--------|-------| | name | lowercase + hyphens | 1-64 chars, no reserved words | | description | text | 1-1024 chars, role + trigger conditions | | tools | array | least privilege principle |

→ See [frontmatter-fields.md](references/frontmatter-fields.md) for detailed rules

Tool Selection Guide

| Pattern | Tools | Purpose | |---------|-------|---------| | Read-only | Read, Grep, Glob, Bash | Exploration/Analysis | | Writer | Read, Write, Edit, Bash | File modification | | Interactive | Read, AskUserQuestion | User questions | | Orchestrator | Read, Write, Task | Subagent coordination |

→ See [tool-selection.md](references/tool-selection.md) for detailed patterns

Model Selection

| Model | Use Case | Cost | |-------|----------|------| | haiku | Fast exploration, simple tasks | ~$0.25/MTok | | sonnet | Balanced choice (default) | ~$3/MTok | | opus | Complex reasoning | ~$15/MTok |

System Prompt Structure

You are {name}, a {specialist type}.

## Your Role
{detailed role description}

## Process
### Step 1: {step name}
{description}

## Output Format
{expected output format}

## Important Notes
- {cautions}

→ See [examples.md](references/examples.md) for complete Agent examples

Design Principles

1. Single Responsibility: Each Agent has one clear role
2. Clear Triggers: Specify usage timing in description
3. Least Privilege: Grant only necessary tools
4. Specific Process: Define step-by-step tasks clearly

Common Mistakes

• ❌ Missing trigger conditions in description
• ❌ Excessive permission grants (listing all tools)
• ❌ Vague role definition
• ❌ Skipping process steps
• ❌ Giving Task tool to Worker Agents

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: houarnu166
• Source: houarnu166/skillful-agent-system-builder
• License: MIT

Install and usage instructions live in the source repository linked above.