ai agent engineer
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# AI Agent Engineer
Expert guidance for engineering and improving AI agents in the IdeaFlow multi-agent system.
## Domain Scope
This skill covers the ai-agent-engineer domain within IdeaFlow:
| Area | Files | Purpose |
| ------------------- | ------------------------------------------------------------ | --------------------------------------- | ----------------------------- | --------------------- |
| Agent Configuration | `.opencode/agents/CMZ.json`, `.opencode/oh-my-opencode.json` | Agent definitions, models, capabilities |
| YH | | Skills Library | `.opencode/skills/*/SKILL.md` | 33 specialized skills |
| Agent Guidelines | `docs/agent-guidelines.md` | 10 core principles, workflows |
| System Integration | `opencode.json`, `AGENTS.md` | CLI config, documentation |
## Agent Architecture
### Primary Orchestrator: CMZ
CMZ (Cognitive Meta-Z) is the main orchestrating agent with three core capabilities:
1. **Self-Heal**: Detect errors, diagnose root cause, implement recovery
2. **Self-Learn**: Integrate feedback, analyze outcomes, build knowledge
3. **Self-Evolve**: Expand capabilities, optimize performance, meta-improve
### Specialized Agents (OhMyOpenCode)
| Agent | Model | Purpose |
| ---------- | -------------- | --------------------------------------- |
| Sisyphus | minimax-m2.5-free | Main orchestrator, relentless execution |
| Hephaestus | glm-4.7-free | Autonomous deep worker |
| Oracle | minimax-m2.5-free | Architecture, debugging, reasoning |
| Librarian | glm-4.7-free | Documentation, exploration |
| Explore | glm-4.7-free | Fast codebase search |
### Categories
| Category | Model | Use Case |
| ------------------ | ----------------- | --------------------------- |
| visual-engineering | glm-4.7-free | UI/Frontend work |
| ultrabrain | minimax-m2.5-free | Complex logic, architecture |
| quick | minimax-m2.1-free | Fast, simple tasks |
| deep | minimax-m2.5-free | Thorough analysis |
## Delegation Patterns
### When to Delegate
```
Task Type → Delegate To
─────────────────────────────────────
Codebase exploration → explore (background)
Documentation lookup → librarian (background)
Complex reasoning → oracle (blocking)
UI/Frontend work → visual-engineering category
Quick fixes → quick category
```
### Delegation Commands
```bash
# Background exploration (parallel)
task(subagent_type="explore", run_in_background=true, prompt="...")
# Blocking consultation
task(subagent_type="oracle", run_in_background=false, prompt="...")
# Category delegation
task(category="visual-engineering", load_skills=["frontend-ui-ux"])
```
## Configuration Management
### Key Files
| File | Purpose |
| ------------------------------- | ---------------------------------------- |
| `opencode.json` | CLI config, model selection, MCP servers |
| `.opencode/oh-my-opencode.json` | Agent definitions, categories, hooks |
| `.opencode/agents/CMZ.json` | CMZ-specific configuration |
### Adding a New Agent
1. Define in `.opencode/oh-my-opencode.json`:
```json
"agents": {
"new_agent": {
"model": "opencode/model-name",
"category": "category-name"
}
}
```
2. Add to CMZ.json if orchestrator integration needed
### Adding a New Skill
1. Create directory: `.opencode/skills/skill-name/`
2. Create `SKILL.md` with frontmatter (name, description)
3. Add references in `references/` if needed
4. Follow skill-creator guidelines for structure
## Self-\* Capabilities
### Self-Heal Implementation
```
Error → Detect → Diagnose → Recover → Learn
```
1. **Detect**: Monitor for exceptions, failed tests, CI failures
2. **Diagnose**: Use systematic-debugging skill, analyze stack traces
3. **Recover**: Implement fix, verify with tests
4. **Learn**: Document in memory, prevent recurrence
### Self-Learn Implementation
```
Feedback → Analyze → Extract → Apply
```
1. **Collect**: User feedback, test outcomes, performance metrics
2. **Analyze**: Identify patterns, successful approaches
3. **Extract**: Generalize into reusable patterns
4. **Apply**: Update skills, configs, documentation
### Self-Evolve Implementation
```
Evaluate → Identify → Implement → Verify
```
1. **Evaluate**: Current capabilities vs requirements
2. **Identify**: Gaps, optimization opportunities
3. **Implement**: New skills, improved delegation
4. **Verify**: Tests pass, metrics improve
## Agent Improvement Workflow
### RESEARCH → PLAN → IMPLEMENT → VERIFY → SELF-REVIEW → DELIVER
1. **RESEARCH**: Explore codebase, gather context
2. **PLAN**: Create detailed work breakdown
3. **IMPLEMENT**: Make atomic changes
4. **VERIFY**: Run tests, lint, type-check
5. **SELF-REVIEW**: Check against requirements
6. **DELIVER**: Create PR with proper labeling
### Verification Checklist
- [ ] All tests pass (`npm test`)
- [ ] Lint passes with zero warnings (`npm run lint`)
- [ ] Type check passes (`npm run type-check`)
- [ ] Build succeeds (`npm run build`)
- [ ] Documentation updated if needed
- [ ] PR has `ai-agent-engineer` label
## Common Tasks
### Improve Agent Configuration
1. Read current config from `.opencode/oh-my-opencode.json`
2. Identify improvement (model change, capability addition)
3. Make atomic change
4. Verify with `opencode` CLI if possible
5. Document change in commit message
### Create New Skill
1. Use `skill-creator` skill for guidance
2. Run `init_skill.py` from skill-creator
3. Write SKILL.md with clear frontmatter
4. Add references for detailed content
5. Validate and test
### Fix Agent Issue
1. Reproduce issue
2. Use `systematic-debugging` skill
3. Implement minimal fix
4. Add regression test
5. Verify fix
## Reference Files
For detailed patterns and examples, see:
- **[Agent Architecture Details](references/agent-architecture.md)**: Deep dive into agent system internals, model selection, and advanced patterns
## Anti-Patterns
| Anti-Pattern | Why Bad | Instead |
| -------------------- | --------------- | ---------------------- |
| Direct main commits | Bypasses review | Use feature branches |
| Skipping tests | Regressions | Always run tests |
| Large atomic changes | Hard to review | Small, focused changes |
| Ignoring CI failures | Ships bugs | Fix all failures |
| Undocumented changes | Knowledge loss | Update documentation |
---
> Source: [cpa03/ai-first](https://github.com/cpa03/ai-first) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Sections and files
Listed in source order.
sections -> Domain Scope → Agent Architecture → Primary Orchestrator: CMZ → Specialized Agents (OhMyOpenCode) → Categories → Delegation Patterns
terms -> Self-Heal · Self-Learn · Self-Evolve · Detect · Diagnose · Recover · Learn · Collect
files/cmd -> .opencode/agents/CMZ.json · .opencode/oh-my-opencode.json · .opencode/skills/*/SKILL.md · docs/agent-guidelines.md · opencode.json · AGENTS.md · .opencode/skills/skill-name/ · references/
body sha256 -> beca57e4b79a
Domain Scope
This skill covers the ai-agent-engineer domain within IdeaFlow: Area · Files · Purpose Agent Configuration ·
.opencode/agents/CMZ.json,.opencode/oh-my-opencode.json· Agent definitions, models, capabilities YH · Skills Library ·.opencode/skills/*/SKILL.md· 33 specialized skills Agent Guidelines ·docs/agent-guidelines.md· 10 core principles, workflowsPrimary Orchestrator: CMZ
CMZ (Cognitive Meta-Z) is the main orchestrating agent with three core capabilities: Self-Heal: Detect errors, diagnose root cause, implement recovery Self-Learn: Integrate feedback, analyze outcomes, build knowledge Self-Evolve: Expand capabilities, optimize performance, meta-improve
Specialized Agents (OhMyOpenCode)
Agent · Model · Purpose Sisyphus · minimax-m2.5-free · Main orchestrator, relentless execution Hephaestus · glm-4.7-free · Autonomous deep worker Oracle · minimax-m2.5-free · Architecture, debugging, reasoning Librarian · glm-4.7-free · Documentation, exploration
Categories
Category · Model · Use Case visual-engineering · glm-4.7-free · UI/Frontend work ultrabrain · minimax-m2.5-free · Complex logic, architecture quick · minimax-m2.1-free · Fast, simple tasks deep · minimax-m2.5-free · Thorough analysis
Key Files
File · Purpose
opencode.json· CLI config, model selection, MCP servers.opencode/oh-my-opencode.json· Agent definitions, categories, hooks.opencode/agents/CMZ.json· CMZ-specific configuration