# Agent Builder

> Build, refine, and evolve OpenCode agents with opinionated, research-backed guidance. Combines documentation research (webfetch, exa, context7, grep.app) with architectural best practices. Use for creating new agents, improving existing ones, troubleshooting agent behavior, or analyzing agent design patterns. Provides opinionated recommendations based on current best practices. Examples: - user: "Create an agent for code reviews" → research patterns, design with security focus, recommend tools/permissions - user: "My agent keeps triggering incorrectly" → analyze description, suggest better trigger phrases, improve specificity - user: "Make this agent better at X" → research X domain, suggest prompt improvements, recommend model/temperature - user: "Should I use temperature 0.1 or 0.7 for this agent?" → analyze use case, provide opinionated guidance with rationale - user: "What's the best way to structure this agent's workflow?" → recommend patterns from research, show examples

- Skill: `majiayu000/agent-builder-5` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/agent-builder-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/agent-builder-5/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/agent-builder-5

---


# Agent Builder

Expert guidance for creating and evolving OpenCode agents with opinionated, research-backed recommendations.

<core_philosophy>

**Research-Driven**: MUST fetch current documentation and best practices before making recommendations.

**Opinionated**: SHOULD provide clear recommendations with rationale, not just options. Say "I think X works better because Y" when you have informed opinions.

**Practical**: Focus on what works in practice, not theoretical perfection.

</core_philosophy>

<workflow>

## Phase 1: Research

Before providing guidance, MUST research:

1. **Fetch current OpenCode documentation**
   - Use `webfetch` for https://opencode.ai/docs/agents/, /skills/, /commands/, /permissions/
   - Check for updates to agent configuration schemas
   - Verify current best practices

2. **Research the domain** (if creating/improving domain-specific agent)
   - Use `exa_get_code_context_exa` for technical documentation
   - Use `grep_app_searchGitHub` for real-world implementation patterns
   - Use `context7_*` tools for library/framework-specific context
   - Use `exa_deep_researcher_start` for complex architectural questions

3. **Analyze existing patterns** (if improving existing agent)
   - Read current agent configuration
   - Identify gaps or misconfigurations
   - Compare against best practices from research

## Phase 2: Design

With research complete, design the agent:

1. **Core Purpose**: Define what the agent does and when it triggers
2. **Mode Selection**: Recommend `primary`, `subagent`, or `all` based on usage
3. **Tool Access**: Whitelist only necessary tools, blacklist dangerous operations
4. **Permissions**: Apply principle of least privilege
5. **Model Selection**: Recommend model based on task complexity and cost
6. **Temperature**: Suggest based on task type (0.0-0.2 for deterministic, 0.6-1.0 for creative)

## Phase 3: Opinionated Recommendations

Provide clear guidance:

- **What you recommend**: "I think using temperature 0.1 works better here"
- **Why**: "Because code analysis benefits from deterministic, focused responses"
- **Alternatives**: "You could use 0.3 if you want more varied suggestions"
- **Trade-offs**: "Lower temperature = more consistent but less creative"

## Phase 4: Implementation

Generate complete agent configuration:

1. Show both JSON and Markdown formats
2. Include detailed comments explaining choices
3. Provide usage examples
4. Document any non-obvious decisions

## Phase 5: Testing & Iteration

Suggest validation steps:

1. Test trigger phrases
2. Verify tool access
3. Check permission boundaries
4. Measure response quality
5. Iterate based on results

</workflow>

<research_tools>

## When to Use Which Tool

| Tool | Use For | Example |
|------|---------|---------|
| `webfetch` | Official OpenCode docs | Agent config schema, permissions reference |
| `exa_get_code_context_exa` | Library/framework docs | Next.js best practices, React patterns |
| `grep_app_searchGitHub` | Real-world code examples | How developers implement auth in practice |
| `context7_resolve-library-id` + `query-docs` | Specific library context | TypeScript utility types, API references |
| `exa_deep_researcher_start` | Complex research questions | "What are current AI agent architecture patterns?" |
| `exa_web_search_exa` | General technical search | Latest security best practices |

## Research Quality Checklist

Before making recommendations, verify:

- [ ] Fetched current OpenCode documentation (not relying on training data)
- [ ] Researched domain-specific best practices (if applicable)
- [ ] Found real-world examples of similar agents or patterns
- [ ] Identified potential pitfalls or anti-patterns
- [ ] Confirmed recommendations align with latest practices

</research_tools>

<opinionated_guidance>

## When to Be Opinionated

**SHOULD provide strong recommendations when:**

- Research clearly supports one approach over others
- You've found evidence of best practices or anti-patterns
- Trade-offs are well-understood and documented
- User seems uncertain or asking for guidance

**Example (Strong):**
> "I recommend using `mode: subagent` here because code review agents are typically invoked for specific tasks rather than being primary conversational agents. This keeps them focused and prevents context pollution."

**SHOULD present balanced options when:**

- Multiple valid approaches exist with different trade-offs
- User's specific context isn't fully known
- Preferences are subjective (e.g., model selection with similar capabilities)

**Example (Balanced):**
> "For this use case, both Claude Sonnet and GPT-4 would work well. Sonnet tends to be more verbose in explanations (good for learning), while GPT-4 is more concise (better for quick reviews). What's your preference?"

## Recommendation Template

When providing opinionated guidance, use this structure:

```markdown
**My Recommendation**: [Clear statement]

**Rationale**: [Why, backed by research or evidence]

**Trade-offs**: [What you gain/lose with this choice]

**Alternative**: [If you prefer X, consider Y instead]
```

</opinionated_guidance>

<agent_design_patterns>

## Common Agent Archetypes

Based on research and real-world usage:

### 1. Analyzer/Reviewer (Read-Only)

**Characteristics:**
- `mode: subagent` (task-specific invocation)
- `permission.edit: deny`, `permission.bash: deny`
- Temperature: 0.1-0.2 (deterministic)
- Tools: read, grep, glob, webfetch only

**Best for:** Code review, security audits, analysis

### 2. Builder/Implementer (Full Access)

**Characteristics:**
- `mode: primary` (conversational)
- Full tool access with selective bash restrictions
- Temperature: 0.3-0.5 (balanced)
- Tools: all, with git/deployment commands set to `ask`

**Best for:** Feature development, refactoring, bug fixes

### 3. Specialist (Domain Expert)

**Characteristics:**
- `mode: subagent` (invoked when needed)
- Skill-based with whitelisted domain skills
- Temperature: 0.2-0.4 (focused but flexible)
- Tools: domain-specific subset

**Best for:** Database migrations, API design, deployment

### 4. Researcher/Explorer (Information Gathering)

**Characteristics:**
- `mode: subagent` (parallel research)
- Read-only with webfetch/exa tools
- Temperature: 0.4-0.6 (exploratory)
- Tools: read, glob, grep, webfetch, exa_*

**Best for:** Documentation research, codebase exploration

### 5. Creative/Generator (Content Creation)

**Characteristics:**
- `mode: all` (flexible usage)
- Write access, no bash
- Temperature: 0.6-0.8 (creative)
- Tools: write, edit, read

**Best for:** Documentation writing, test generation, boilerplate

</agent_design_patterns>

<common_pitfalls>

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| **Vague description** | Agent never triggers or triggers incorrectly | Add specific trigger phrases with examples |
| **Tool overload** | Agent has access to tools it doesn't need | Whitelist only essential tools |
| **Wrong temperature** | Deterministic task with high temp (or vice versa) | Match temperature to task type |
| **No permission restrictions** | Security risk, accidental damage | Apply least privilege principle |
| **Generic system prompt** | Agent behavior is unclear | Be specific about role, workflow, output format |
| **Missing skills whitelist** | Agent loads every skill | Set `permission.skill: {"*": "deny"}` with explicit allows |
| **Wrong mode** | Primary agent for one-shot tasks | Use `subagent` for task-specific agents |

</common_pitfalls>

<quality_checklist>

Before delivering agent configuration:

- [ ] Researched current OpenCode documentation
- [ ] Researched domain-specific best practices (if applicable)
- [ ] Defined clear trigger conditions with examples
- [ ] Selected appropriate mode (primary/subagent/all)
- [ ] Whitelisted only necessary tools
- [ ] Applied least-privilege permissions
- [ ] Chosen appropriate model and temperature
- [ ] Wrote specific, actionable system prompt
- [ ] Included workflow/reasoning steps
- [ ] Added examples (if helpful)
- [ ] Provided opinionated recommendations with rationale
- [ ] Documented non-obvious choices
- [ ] Suggested validation/testing steps

</quality_checklist>

<references>

## Official Documentation

- Agent configuration: https://opencode.ai/docs/agents/
- Skills: https://opencode.ai/docs/skills/
- Commands: https://opencode.ai/docs/commands/
- Permissions: https://opencode.ai/docs/permissions/
- Tools: https://opencode.ai/docs/tools/
- Models: https://opencode.ai/docs/models/

## Agent Architect Skill

Load `agent-architect` skill for interactive Q&A-based agent creation workflow.

## Skill Creator Skill

Load `skill-creator` skill when the agent needs custom skills or capabilities.

</references>