| name | ai-agent-engineer |
| description | AI Agent Engineering best practices for OpenX Basefly. Use when working on branch 'ai-agent-engineer', improving agent configurations, skills, or multi-model orchestration. Triggers: agent configuration changes, skill creation/updates, model selection decisions, agent workflow improvements. Use when this capability is needed. |
AI Agent Engineer
Best practices for engineering AI agents in the OpenX Basefly multi-model harness.
Core Principles
1. Model Selection
Match model capabilities to task requirements:
| Task Type | Recommended Model | Rationale |
|---|
| Orchestration | opencode/kimi-k2.5-free | Complex reasoning, coordination |
| Architecture/Debug | opencode/glm-4.7-free | Deep analysis, precision |
| Quick searches | opencode/gpt-5-nano | Speed, cost efficiency |
| Visual/UI | opencode/minimax-m2.1-free | Multimodal understanding |
2. Agent Configuration
When modifying .opencode/oh-my-opencode.json:
- Temperature: Lower (0.2-0.4) for precision tasks, higher (0.6-0.8) for creative tasks
- Categories: Use domain-specific categories for optimal model routing
- Skills: Enable only needed skills to minimize context bloat
3. Skill Development
Follow the skill-creator patterns:
- Keep SKILL.md under 500 lines
- Use progressive disclosure (references/, assets/)
- Clear frontmatter with name and description
- Imperative/infinitive form in instructions
Workflow
Making Improvements
- Read documentation - Check AGENTS.md, skills.md, and relevant SKILL.md files
- Check open PRs/issues - Avoid duplicate work
- Make small changes - Single, focused improvements
- Verify no regression - Run build, lint, test
- Create/update PR - Use appropriate labels
Branch Convention
- Branch name:
ai-agent-engineer
- Label:
ai-agent-engineer
- Keep up-to-date with default branch
- Use
/start-work to execute implementation plans
Planning Skills
When implementing improvements, use the planning skills for structured execution:
writing-plans - Create detailed implementation plans with task breakdownsexecuting-plans - Execute plans with review checkpoints
These skills help maintain focus and verify completeness.
Available Agents
| Agent | Model | Use Case |
|---|
| Sisyphus | opencode/kimi-k2.5-free | Main orchestrator |
| Oracle | opencode/glm-4.7-free | Architecture, debugging |
| Librarian | opencode/glm-4.7-free | Documentation, research |
| Explore | opencode/gpt-5-nano | Fast exploration |
| Multimodal Looker | opencode/minimax-m2.1-free | Visual/UI tasks |
| Metis | opencode/glm-4.7-free | Pre-planning consultant |
| Momus | opencode/glm-4.7-free | Expert reviewer, plan evaluation |
Verification Checklist
Before submitting changes:
Common Patterns
Adding a New Skill
scripts/init_skill.py <skill-name> --path .opencode/skills/
Updating Agent Configuration
- Edit
.opencode/oh-my-opencode.json
- Update
.opencode/skills.md if adding new skills
- Update
AGENTS.md if changing agent roles
- Test with actual agent interactions
Temperature Guidelines
| Temperature | Use Case |
|---|
| 0.1-0.3 | Factual, deterministic responses |
| 0.4-0.6 | Balanced reasoning |
| 0.7-0.9 | Creative, exploratory |
Troubleshooting
Common Issues
Model Not Responding Correctly
- Check temperature settings - Lower temperature (0.2-0.4) for precision tasks
- Verify model availability - Ensure the model ID is correct in
oh-my-opencode.json
- Test with simpler prompts - Isolate the issue with basic queries
Skill Not Loading
- Verify skill path - Check
skills.sources in oh-my-opencode.json
- Check skill enable list - Ensure skill is in
skills.enable array
- Validate SKILL.md format - Ensure proper YAML frontmatter
Context Window Issues
- Disable unused skills - Remove from
skills.enable array
- Disable unused MCP servers - Set
enabled: false in MCP configuration
- Use specialized agents - Delegate to
explore or librarian for focused tasks
Category Routing Issues
- Check category definitions - Verify category exists in
oh-my-opencode.json
- Verify model assignment - Each category should have a model and temperature
- Test category directly - Use
task(category="...", ...) to verify
Debugging Steps
- Check configuration file - Validate JSON syntax in
oh-my-opencode.json
- Review agent logs - Look for error messages in agent output
- Test in isolation - Create minimal test case to isolate issue
- Compare with working config - Diff against known working configuration
References
- model-capabilities.md - Detailed model capability matrices, agent-to-model mapping, and performance tips
- mcp-servers.md - MCP server configuration, available servers, and best practices
Source: cpa03/basefly — distributed by TomeVault.
