Agentopology Skill

Step 5: Scaffold (if requested)

Preview first, then execute:

agentopology scaffold <file.at> --target <target> --dry-run

Show what will be created. If reasonable, proceed without asking:

agentopology scaffold <file.at> --target <target>

Report what was generated. Done.

Mode: Validate (--validate)

agentopology validate <file.at>

There are 82 validation rules. If all pass, tell the user. If errors, explain each one clearly and offer to fix. Query agentopology docs validation for rule explanations if needed.

If no file specified, look for .at files in the current directory and .claude/topologies/.

Mode: Scaffold (--scaffold)

Ask for target if not specified:

Targets:
  claude-code    Anthropic Claude Code CLI
  codex          OpenAI Codex CLI
  gemini-cli     Google Gemini CLI
  copilot-cli    GitHub Copilot CLI
  openclaw       OpenClaw framework
  kiro           AWS Kiro CLI

Or run agentopology targets to get the live list.

Then dry-run → show preview → execute on approval.

Incremental scaffolding: The CLI tracks generated files via .scaffold-manifest.json. On subsequent runs:

• Only changed files are updated. Unchanged files are skipped.
• User edits to ## Instructions sections in AGENT.md files are preserved across re-scaffolds.
• Use --prune to delete files that are no longer in the topology.
• Use --force to overwrite everything (ignores manifest, loses user edits).

Mode: Visualize (--visualize)

agentopology visualize <file.at>

The CLI generates an HTML file and opens it in the default browser. Tell the user the output path.

Also available:

• agentopology export <file> --format mermaid — Mermaid diagram
• agentopology export <file> --format markdown — documentation export
• agentopology export <file> --format json — raw AST dump

Mode: Import (--import)

Reverse-engineer existing platform files into a .at file.

agentopology import --target claude-code --dir .claude/

The CLI reads the platform files, generates a .at file, and runs validation on it. Supported targets: claude-code, codex, gemini-cli, copilot-cli, openclaw, kiro.

Mode: Evolve (--evolve)

Modify an existing topology — the .at file is the source of truth, platform files follow.

Direction 1 — User edited platform files, sync back to .at:

1. agentopology sync <file.at> --target claude-code --dir .claude/
2. agentopology validate <file.at>

Direction 2 — User wants to change the topology:

1. Read the .at file, discuss changes with user.
2. Query agentopology docs <relevant-topics> for correct syntax of new constructs.
3. Edit the .at file.
4. agentopology validate <file.at> — verify changes.
5. agentopology scaffold <file.at> --target <binding> --dry-run — preview.
6. agentopology scaffold <file.at> --target <binding> — apply.

Use agentopology info <file> to analyze the current topology structure before suggesting changes.

Generation Rules

When generating .at files:

1. Query before writing. Always run agentopology docs <topic> for every block type you're about to write. Never guess syntax.
2. Keep it simple. 2-4 agents is the sweet spot. Never generate more than 6 unless the user explicitly asks.
3. Pick the right model. haiku for cheap/fast, sonnet for most work, opus only for critical thinking.
4. Always validate. Run agentopology validate after generating. Fix any errors before the user sees them.
5. Name things well. Use descriptive kebab-case names: code-reviewer, security-scanner, report-writer.
6. Include description. Every agent should have a description field explaining its role.
7. Minimal complexity. Start simple. Only add advanced constructs (gates, hooks, metering, etc.) when the user asks or when the use case clearly requires them.
8. Use the full language. Don't artificially limit yourself. If the user needs hooks, gates, metering, providers, or any other construct — query the docs and use it. Every feature in agentopology docs is available.

CLI Command Reference

All commands available to this skill:

# Language reference (42 topics, parser-verified)
agentopology docs                        # List all topics
agentopology docs <topic>                # Show specific topic
agentopology docs --all                  # Dump everything (~3000 lines)
agentopology docs --search <term>        # Search across all topics

# Core workflow
agentopology validate <file.at>          # Parse + run 82 validation rules
agentopology scaffold <file.at> --target <binding> [--dry-run] [--force] [--prune]
agentopology sync <file.at> --target <binding> --dir <path>
agentopology visualize <file.at>

# Analysis & export
agentopology info <file.at>              # Detect patterns, layers, suggestions
agentopology export <file.at> --format <markdown|mermaid|json>

# Reverse engineering
agentopology import --target <binding> --dir <path>

# Discovery
agentopology targets                     # List all binding targets

Principles

1. Speed is the feature. Users should go from idea to working agent configs in under 2 minutes.
2. CLI is the source of truth. Never hardcode syntax. Always query agentopology docs.
3. Opinionated defaults. Don't ask — decide. If pipeline fits, recommend pipeline. Generate and move on.
4. Simple patterns only. 5 patterns cover 90% of use cases.
5. Structure over quantity. 3 focused agents beat 10 unfocused ones. Coordination tax is real.
6. Generate, don't explain. Show the .at file, not a lecture about topology theory.
7. Validate everything. Never give the user an invalid file. Fix it before they see it.
8. The .at file is the product. Everything else (scaffold, visualize) is a bonus.