cli-setup

When invoked:

1. Confirm the context. Ask the user what they're trying to do — a quick code-reviewer, a docs helper, something else. A 30-second clarification up front prevents a misaligned configuration.

2. Walk the four customization layers IN ORDER, stopping at the user's confirmation between each:

   1. Provider + model — .agents/config.json
   2. Personality — AGENTS.md
   3. (Optional) Skills — .agents/skills/<name>/SKILL.md
   4. (Optional) MCP servers — .agents/mcp.json

   For each layer, propose a starting configuration based on the user's stated goal, explain why those choices, and ask for confirmation or adjustments before writing files.

3. Set the permission posture. After the four layers are in place, walk the user through choosing a starting mode (ask for new projects, allow with a curated allowlist for established workflows). Use the references/permission-posture.md reference for the patterns.
4. Verify it works. Suggest the user run core-agent and try a representative prompt. If anything misbehaves, diagnose against the failure modes in the references below.
5. Check it in. Remind the user to git add .agents/ AGENTS.md && git commit so teammates inherit the configuration.

Triggers in detail

The description above lists the verbatim phrasings. Also match on:

• "Help me write an AGENTS.md"
• "How do I tell the agent to use X library / follow Y convention"
• "What should I put in config.json"
• "Add a skill for [domain]"
• "Wire up [MCP server] so the agent can [capability]"
• "The agent keeps asking me before [common operation] — make it stop"

References

Use these references when the user's question is more specific than the runbook above. Fetch with read_file; only the relevant one for the user's current question, not all of them up front.

• references/agents-md-patterns.md — AGENTS.md authoring patterns. Read when the user is writing their personality file or asking why their existing one isn't producing the behavior they want.
• references/skills-and-mcp.md — Extending the tool surface: when to write a skill vs an AGENTS.md rule, and how to wire MCP servers. Read when the user wants the agent to do something the built-in tools don't cover.
• references/permission-posture.md — Choosing between ask / allow / yolo, writing allow patterns, the path-scope safety floor. Read when the user is being prompted too often (or not often enough).

Procedure: provider + model

The minimal .agents/config.json:

{
  "version": 1,
  "model": {
    "provider": "anthropic-vertex",
    "name": "claude-opus-5"
  }
}

Pick the provider based on what credentials the user has. Don't auto-detect from env vars in a checked-in config — that depends on per-operator environment and breaks reproducibility.

Model picks:

• Coding-heavy work: claude-opus-5 OR gemini-3.1-pro-preview-customtools (the customtools variant prefers function-tools over raw shell; recommended for coding agents).
• Lighter Q&A, doc explanation: claude-sonnet-5 OR gemini-3.5-flash-lite (both much cheaper).
• Mixed: claude-opus-5 parent + --agentic-tools --agentic-small-model claude-haiku-4-5 for cost-efficient tool work.

Procedure: AGENTS.md

Walk the user through writing the role + scope + house style + do/don't list. Fetch references/agents-md-patterns.md if they're stuck on what to put.

The minimum viable AGENTS.md is ~15 lines: one paragraph defining the role, one section listing what's in scope, one section with 3-5 house-style rules, one "don't do" list with 2-3 specific anti-patterns. Resist the urge to make it longer — long AGENTS.md dilutes attention.

Procedure: skills

Most projects start with zero skills and add them as recurring procedures surface. If the user is asking for a skill, fetch references/skills-and-mcp.md for the design patterns.

Quick test: if the procedure applies to every turn of any task, it's AGENTS.md content. If it applies to specific named requests, it's a skill.

Procedure: MCP servers

Wire MCP only if the user needs capabilities outside the built-in nine tools (read_file, read_many_files, write_file, edit_file, list_dir, glob, grep, bash, todo). Common MCP additions: web search (tavily), GitHub API, internal databases.

Fetch references/skills-and-mcp.md for mcp.json schema + the namespacing rules.

Procedure: permission posture

Walk through the modes table:

Fetch references/permission-posture.md for the pattern grammar (bash:git diff*, read_file:internal/**) and the path-scope safety floor.

When NOT to use this skill

• The user is asking about autonomous / headless configuration (long-running unattended workers). Use the autonomous-setup skill instead.
• The user is embedding core-agent in their own Go binary rather than using the CLI. Use the library-embedding skill instead.
• The user is asking a quick reference question ("what flag disables compaction?") — answer directly from the docs, don't walk the whole runbook.
• The user has an existing well-configured agent and is asking about a specific failure mode. Investigate the failure first; only walk the configuration runbook if the failure traces back to a missing/misconfigured layer.

Output style

Conversational. For each layer, propose → confirm → write → next. Don't dump the entire 4-layer configuration up front; that's overwhelming. Walk one layer at a time, showing the user what's about to land in their repo.

When writing files, use write_file (or edit_file if updating). Show the user what's about to be written before writing it; ask for adjustments. Once written, briefly confirm and move to the next layer.