Agent Setup

AI DevKit separates machine integration from project workflow configuration:

1. Run ai-devkit setup once per machine. It connects detected local agents, installs their available session integrations, and installs built-in skills globally.
2. Run ai-devkit init once per project. It creates .ai-devkit.json and workflow docs, then reconciles configured project skills and MCP files.
3. Run ai-devkit install later when you need to reconcile installable project artifacts from .ai-devkit.json.

Start with the complete Getting Started flow, including the separate global-install, npx-only, and CI paths.

For teams adopting AI coding agents across multiple tools, this setup becomes the shared foundation of the control plane: one config that generates workflow docs and reconciles project skills and MCP server files.

Before running these commands:

• Install AI DevKit (npm install -g ai-devkit) and run ai-devkit setup, or use npx ai-devkit@latest setup
• Run commands from your project root directory
• Make sure you have permission to create or update agent-related files in the repository

Global npm installation does not run setup automatically. If you use npx only, prefix every command on this page with npx ai-devkit@latest.

Key concepts:

• Environment: An AI coding tool you use in the project. It determines where AI DevKit installs configured skills and MCP servers.
• Phase: A stage of the software development lifecycle, such as requirements, design, or testing. AI DevKit provides document templates for each phase.

When to Use setup, init, and install#

Use ai-devkit setup when:

• You are connecting AI DevKit to agents on a machine for the first time
• You installed or launched another supported agent and want AI DevKit to detect it
• You need to restore global built-in skills or a session integration

Use ai-devkit init when:

• You are setting up AI DevKit in a project for the first time
• You want interactive prompts to choose environments and phases
• You want non-interactive bootstrap from a template file (ai-devkit init --template)
• You need project workflow docs and configured skills or MCP files

Use ai-devkit install when:

• .ai-devkit.json already exists
• You want deterministic setup without re-answering prompts
• You want to restore missing phase docs, skills, or MCP files to match your config

Basic Usage#

After completing machine setup, the simplest project path is interactive initialization. This walks you through choosing environments and phases:

ai-devkit init

Once .ai-devkit.json exists in your project, apply or re-apply the setup with:

ai-devkit install

After install completes successfully, you should usually see:

• .ai-devkit.json in your project root
• Environment-specific skill folders such as .cursor/skills/, .claude/skills/, .github/skills/, or .agents/skills/
• MCP config files such as .mcp.json or .codex/config.toml if your config includes MCP servers for supported environments

After running, you will see a summary like:

✔ Install Summary
  ✔ 3 environment(s) installed
  ✔ 5 phase template(s) installed
  ✔ 2 skill(s) installed

Use a non-default config file if your project stores AI DevKit config elsewhere:

ai-devkit install --config ./.ai-devkit.team.json

Overwrite existing install artifacts without extra prompts:

ai-devkit install --overwrite

What ai-devkit install Sets Up#

Based on your configured environments, AI DevKit installs or updates files such as:

• Agent skill files (for example .cursor/skills/, .claude/skills/, .github/skills/ for GitHub Copilot, .devin/skills/, and .agents/skills/ for Codex) refer Skills for more on skills
• MCP server configuration files (.mcp.json for Claude Code and GitHub Copilot, .codex/config.toml for Codex, opencode.json for opencode, .junie/mcp/mcp.json for Junie, .devin/config.json for Devin, .roo/mcp.json for Roo Code, .kilo/kilo.jsonc for Kilo Code) The exact artifacts depend on the environments configured in .ai-devkit.json. ai-devkit install only manages project-local files generated from that config.

Team Onboarding#

Once .ai-devkit.json is committed to your repository, teammates and CI pipelines can reproduce the same setup with a single command:

ai-devkit install

Each teammate still needs the AI DevKit CLI available locally. With a global installation, run ai-devkit setup once and then use ai-devkit install. With npx only, use npx ai-devkit@latest setup once and prefix the install command too: npx ai-devkit@latest install.

Template-based Setup#

For repeatable, non-interactive setup, create a template file. This is useful for sharing a standard configuration across teams or running in CI.

Create a file named fullstack-engineer.yaml in your project root with this content:

environments:
  - cursor
  - claude
  - codex
phases:
  - requirements
  - design
  - planning
  - implementation
  - testing
paths:
  docs: docs/ai
skills:
  - registry: codeaholicguy/ai-devkit
    skill: structured-debug
    mode: copy # optional: copy or link (default)
  - registry: codeaholicguy/ai-devkit
    skill: dev-lifecycle

Initialize from that template:

ai-devkit init --template ./fullstack-engineer.yaml

Use a custom directory for AI documentation in either interactive or template mode (default is docs/ai):

ai-devkit init --docs-dir ./ai-docs

Adding MCP Servers to a Template#

Templates can include MCP server definitions. Add a mcpServers section to your template:

Note: mcpServers support requires AI DevKit 0.23.0 or later.

mcpServers:
  memory:
    transport: stdio
    command: npx
    args:
      - -y
      - "@ai-devkit/memory"

The -y flag lets npx run non-interactively, which is recommended for repeatable setup and CI.

After running ai-devkit init --template, MCP server definitions are saved to .ai-devkit.json. Run ai-devkit install to generate the agent-specific MCP config files. For the full mcpServers field reference, see Configuration File.

Template Field Reference#

*If omitted, ai-devkit init will prompt you to select them interactively. Required for fully non-interactive runs.

Built-in Skills in CI#

For normal local onboarding, ai-devkit setup installs built-in skills globally for detected agents. In non-interactive environments such as CI, pass --built-in to init when the job needs project-local copies:

ai-devkit init --yes --environment <environment> --all --built-in

The --all flag selects all available phases. Combined with --yes, --environment, and --built-in, this gives a fully non-interactive project initialization.

When using a template with a skills section, skills from the template are installed from that configuration. Avoid combining the template with --built-in unless you intentionally want built-in skills added separately.

MCP Servers#

MCP (Model Context Protocol) servers give AI agents extended capabilities such as persistent memory, database access, or external tool integrations. Define MCP servers in .ai-devkit.json and AI DevKit generates the environment-specific config files for you.

Note: mcpServers generation and install flow require AI DevKit 0.23.0 or later.

MCP configuration is currently generated for Cursor (.cursor/mcp.json), Claude Code (.mcp.json), GitHub Copilot (.mcp.json), Gemini CLI (.gemini/settings.json), Codex (.codex/config.toml), opencode (opencode.json), Junie (.junie/mcp/mcp.json), Devin (.devin/config.json), Roo Code (.roo/mcp.json), and Kilo Code (.kilo/kilo.jsonc).

If your project uses only environments that do not currently support MCP generation, AI DevKit still saves the mcpServers definitions in .ai-devkit.json, but no environment-specific MCP config files are created.

You can define the same mcpServers configuration either in a template file used with ai-devkit init --template or directly in .ai-devkit.json. Both approaches work. After initialization, ai-devkit install always reads the final mcpServers values from .ai-devkit.json.

For the full mcpServers field reference, supported keys, and transport-specific examples, see Configuration File.

Example Configuration#

Add an mcpServers object to .ai-devkit.json like this:

{
  "mcpServers": {
    "memory": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@ai-devkit/memory"],
      "env": { "DB": "./db" }
    },
    "notion": {
      "transport": "http",
      "url": "https://mcp.notion.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Then run ai-devkit install to generate the MCP config files for each supported environment.

Conflict Resolution#

When ai-devkit install finds an existing MCP server with the same name but different configuration:

• Interactive mode: You are prompted to skip, overwrite all, or choose per server.
• Non-interactive mode (CI): Conflicts are skipped by default. Pass --overwrite to force replacement.

Servers not managed by AI DevKit are preserved and never modified.

Troubleshooting#

.ai-devkit.json not found#

Run:

ai-devkit init

This creates the configuration file used by install.

If you prefer non-interactive setup, use the template command shown in Template-based Setup.

Existing files are not updated#

If you want to force replacement of install-managed artifacts, run:

ai-devkit install --overwrite

I changed environments but setup still looks old#

Re-run:

ai-devkit install

This re-applies setup using the current .ai-devkit.json content.

Next Steps#

• Configuration File
• Supported AI Agents & Environments
• Getting Started
• Development with AI DevKit