Create Agent

Creates and registers new Overstory agents so Overclaw can recognize and use them. Automates the steps documented in .overstory/CREATING_AGENTS.md.

When to use

• You want to add a new agent type (e.g. troubleshooter, docs-writer) to Overclaw.
• You want to ensure all seven integration points are updated consistently.
• You want to suggest new agents from Overclaw logs, TROUBLESHOOTING.md, mulch, or project structure.

Scripts

create_agent.py

Main CLI for creating or validating agents.

Manual creation:

python3 scripts/create_agent.py \
  --name "troubleshooter" \
  --description "Analyzes logs and troubleshoots issues" \
  --capabilities "troubleshoot,debug,analyze" \
  --model "sonnet" \
  --tools "Read,Glob,Grep,Bash" \
  --can-spawn false \
  --constraints "read-only"

Options: --dry-run (preview only), --no-regenerate (skip gateway context regeneration), --rollback-on-fail (revert changes if validation fails).

Analysis mode (suggestions only):

python3 scripts/create_agent.py \
  --analyze-from-logs \
  --analyze-from-troubleshooting \
  --suggest-only

analyze_agent_needs.py

Helper for analysis mode: parses logs, TROUBLESHOOTING.md, mulch, and project tree to suggest new agent definitions. Can be run standalone or via create_agent.py --analyze-*.

Integration points updated

1. .overstory/config.yaml — capability entry
2. .overstory/agent-manifest.json — agent + capabilityIndex
3. .overstory/agent-defs/.md — agent definition
4. scripts/overclaw_gateway.py — orchestrator system prompt
5. skills/nanobot-overstory-bridge/scripts/task_router.py — CAPABILITY_PATTERNS
6. skills/nanobot-overstory-bridge/scripts/generate_agent_context.py — CAPABILITY_PRIVILEGES
7. Regeneration of gateway-context.md and skills-manifest.json

References

• CREATING_AGENTS.md — Step-by-step explainer
• .overstory/agent-defs/blogger.md — Example agent def
• .overstory/agent-defs/supervisor.md — Example coordinator-style agent