Nano - OpenCode Agents Project

A minimal project structure for creating and managing custom OpenCode agents.

Project Structure

nano/
├── opencode.json           # Main agent configuration
├── .opencode/agent/        # Custom agents (markdown format)
│   └── docs-writer.md     # Documentation writer agent
├── prompts/               # Agent prompt files
│   ├── build.txt          # Build agent prompt
│   ├── cleanup.txt        # Cleanup agent prompt
│   ├── security.txt       # Security auditor prompt
│   └── review.txt        # Code review prompt
└── README.md             # This file

Available Agents

Primary Agents

• build: Full development agent with all tools enabled
• plan: Analysis and planning agent (read-only)

Subagents

• @cleanup: Repository cleanup and maintenance
• @security: Security auditing and vulnerability assessment
• @docs-writer: Technical writing and documentation
• @review: Code review and quality assessment

Usage

Switching Between Primary Agents

Use Tab key to cycle between build and plan agents.

Using Subagents

Mention subagents with @ in your messages:

@cleanup help me clean up this repository
@security audit this code for vulnerabilities
@docs-writer create documentation for this API
@review review my recent changes

Configuration

Adding New Agents

1. JSON Configuration: Edit opencode.json
2. Markdown Files: Add new .md files to .opencode/agent/
3. Prompt Files: Add corresponding prompts to prompts/

Agent Types

• Primary: Main agents you interact with directly
• Subagent: Specialized agents invoked for specific tasks

Customization

Models

Each agent can use different models optimized for their tasks:

• Fast models for planning and analysis
• Capable models for implementation
• Specialized models for specific domains

Tools & Permissions

Configure which tools each agent can access:

• File operations (read, write, edit)
• System commands (bash)
• Web access (webfetch)
• Custom permissions and restrictions

Temperature

Control creativity vs. determinism:

• 0.0-0.2: Focused, analytical tasks
• 0.3-0.5: Balanced development work
• 0.6-1.0: Creative and exploratory tasks

Examples

Repository Cleanup

@cleanup analyze this repository and suggest cleanup

Security Audit

@security check for security vulnerabilities in this code

Documentation Generation

@docs-writer create API documentation for this module

Code Review

@review review my recent commits for best practices

Development

Creating New Agents

Use OpenCode CLI to create new agents:

opencode agent create

Testing Agents

Test agents in isolation before integrating:

@new-agent test this functionality

Agent Configuration Examples

JSON Configuration

{
  "agent": {
    "my-agent": {
      "description": "Custom agent for specific task",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": "{file:./prompts/my-agent.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false
      }
    }
  }
}

Markdown Configuration

---
description: Custom agent for specific task
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.3
tools:
  write: true
  edit: true
  bash: false
---

You are a specialized agent for...

Agent Permissions

Permission Levels

• allow: Grant unrestricted access
• ask: Prompt for confirmation before action
• deny: Completely disable the tool

Example Permissions

{
  "permission": {
    "bash": {
      "git push": "ask",
      "git status": "allow",
      "*": "deny"
    },
    "edit": "ask",
    "webfetch": "allow"
  }
}

Best Practices

Agent Design

• Keep agents focused on specific tasks
• Use appropriate temperature settings
• Configure minimal necessary permissions
• Write clear, specific prompts

Security

• Restrict dangerous operations with permissions
• Use ask for potentially destructive actions
• Review agent configurations regularly

Performance

• Use faster models for simple tasks
• Reserve powerful models for complex work
• Consider token usage and costs

Resources

• OpenCode Documentation
• Agent Configuration Guide
• Available Models
• Permissions Documentation

Contributing

To contribute new agents or improvements:

1. Fork the project
2. Create a new branch
3. Add your agent configuration
4. Test thoroughly
5. Submit a pull request

License

This project is provided as a template for OpenCode agent development. Feel free to adapt and modify for your specific needs.