agent-tuning

name	agent-tuning
description	Configure and optimize AI coding agents (OpenCode/Claude). Use when setting up or improving agent behavior.

Configuration Locations

OpenCode

~/.config/opencode/
├── opencode.json          # Main config
├── agent/                 # Custom agent prompts
│   ├── oscar.md
│   ├── scout.md
│   ├── ivan.md
│   └── jester.md
├── skills/                # Reusable skills
│   └── <name>/SKILL.md
└── rules/                 # Always-active rules
    └── RULES.md

Claude Code

~/.claude/
├── settings.json          # Main config
├── agents/                # Custom agents
│   └── <name>.md
├── skills/                # Reusable skills
│   └── <name>/SKILL.md
└── CLAUDE.md              # Global instructions

Agent File Structure

Frontmatter (YAML)

---
tools:
  read: true
  write: false
  edit: false
  glob: true
  grep: true
  bash: true
  task: false
  webfetch: true
  todoread: true
  todowrite: true
  question: true    # Ask user questions
  skill: true       # Load skills

permission:
  bash:
    "git *": allow
    "gh *": allow
    "*": deny
---

Tool Reference

Tool	Purpose	Risk Level
read	Read files	Low
write	Create/overwrite files	High
edit	Modify files	High
glob	Find files by pattern	Low
grep	Search file contents	Low
list	List directories	Low
bash	Execute commands	Variable
task	Delegate to subagents	Low
webfetch	Fetch web content	Medium
todoread	Read task list	Low
todowrite	Update task list	Low
question	Ask user questions	Low
skill	Load skill files	Low

Permission Patterns

Restrictive (Read-Only Agent)

tools:
  read: true
  write: false
  edit: false
  bash: true

permission:
  bash:
    "ls *": allow
    "cat *": allow
    "git status": allow
    "*": deny

Permissive (Full Access)

tools:
  read: true
  write: true
  edit: true
  bash: true

permission:
  bash:
    "*": allow

Balanced (Common Pattern)

tools:
  read: true
  write: true
  edit: true
  bash: true

permission:
  bash:
    # Safe commands
    "ls *": allow
    "cat *": allow
    "head *": allow
    "tail *": allow
    
    # Git operations
    "git *": allow
    
    # Python in venv only
    ".venv/bin/*": allow
    
    # Deny everything else
    "*": deny

Agent Roles

Orchestrator (Oscar-style)

• Has task: true to delegate
• Has question: true to interact with user
• Limited direct tool access
• Coordinates other agents

Researcher (Scout-style)

• Read-only access
• Has webfetch: true
• Full search tools (glob, grep)
• No task (can't delegate)

Implementor (Ivan-style)

• Full write access
• Full bash access
• No task (can't delegate)
• Does the actual work

Reviewer (Jester-style)

• Read-only access
• Different model for diversity
• Challenges assumptions
• No write access

Tuning Tips

1. Start Restrictive

Begin with minimal permissions, expand as needed.

2. Use Specific Bash Patterns

# Good - specific
".venv/bin/pytest *": allow

# Bad - too broad
"*pytest*": allow

3. Separate Concerns

• Orchestrator: coordinates
• Researcher: investigates
• Implementor: changes code
• Reviewer: validates

4. Test Permission Changes

After modifying permissions, test that:

• Allowed commands work
• Denied commands are blocked
• Edge cases are handled

Debugging

Check Active Config

# OpenCode
cat ~/.config/opencode/opencode.json

# View agent prompt
cat ~/.config/opencode/agent/<name>.md

Common Issues

• Tool not working: Check tools: section
• Command denied: Check permission.bash patterns
• Skill not loading: Check skill name matches directory
• Agent not found: Check opencode.json agent definitions