# How to Add a New AI Agent to the Specify CLI Using the AGENT_CONFIG Structure

> Learn to add a new AI agent to Specify CLI by registering it in AGENT_CONFIG. This guide simplifies adding custom agents for enhanced project management.

- Repository: [GitHub/spec-kit](https://github.com/github/spec-kit)
- Tags: how-to-guide
- Published: 2026-03-05

---

**To add a new AI agent to the Specify CLI, you must register the agent in both the `AGENT_CONFIG` dictionary in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) and the `CommandRegistrar.AGENT_CONFIGS` dictionary in [`src/specify_cli/extensions.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/extensions.py), then optionally define a command-line alias.**

The Specify CLI (spec-kit) provides a pluggable architecture for AI assistants that automates project scaffolding, command template discovery, and skill installation. When you need to integrate a new AI agent into the workflow, you must configure the `AGENT_CONFIG` structure to declare metadata and the `CommandRegistrar.AGENT_CONFIGS` structure to define how command templates are stored and parsed.

## Understanding the Dual-Table Architecture

The CLI discovers agents through two complementary runtime tables:

- **`AGENT_CONFIG`** ([`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py), lines 27‑63): Holds high‑level metadata required for project scaffolding, help‑text generation, and CLI tool validation.
- **`CommandRegistrar.AGENT_CONFIGS`** ([`src/specify_cli/extensions.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/extensions.py), lines 90‑86): Describes how an agent’s extension files are stored (directory, format, argument placeholder, and file extension). This table drives the `install_ai_skills` workflow.

You must insert a matching entry in **both** tables for the CLI to fully recognize the new agent.

## Step 1: Register the Agent in AGENT_CONFIG

Open [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) and add a new entry to the `AGENT_CONFIG` dictionary. The key must match the exact CLI executable name.

```python

# src/specify_cli/__init__.py

AGENT_CONFIG = {
    # … existing agents …

    "myai": {                                       # Key = executable name

        "name": "MyAI Assistant",                   # Human‑readable label

        "folder": ".myai/",                         # Project sub‑directory to create

        "commands_subdir": "commands",              # Where command templates live

        "install_url": "https://example.com/install",  # Docs URL (or None)

        "requires_cli": True,                       # True if host needs the binary

    },
}

```

This configuration drives:

- Generation of the **`--ai`** help text (`AI_ASSISTANT_HELP` is built from this dict).
- Folder creation during `specify init`.
- CLI tool availability checks via `check_tool` when `requires_cli` is `True`.

## Step 2: Configure Command Template Storage in CommandRegistrar.AGENT_CONFIGS

Next, open [`src/specify_cli/extensions.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/extensions.py) and register the agent in the `CommandRegistrar.AGENT_CONFIGS` dictionary. This tells the `install_ai_skills` function where to find and how to parse the agent’s command templates.

```python

# src/specify_cli/extensions.py

class CommandRegistrar:
    AGENT_CONFIGS = {
        # … existing agents …

        "myai": {
            "dir": ".myai/commands",   # Path to command template files

            "format": "markdown",      # "markdown" or "toml"

            "args": "$ARGUMENTS",      # Placeholder string for arguments

            "extension": ".md",        # File extension to match

        },
    }

```

When users run `specify install-skills`, the CLI reads templates from `dir`, parses front‑matter according to `format`, and substitutes the `args` placeholder when generating the final skill files.

## Step 3: (Optional) Define a CLI Alias

If you want a short alias (e.g., `my` → `myai`), add an entry to `AI_ASSISTANT_ALIASES` in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py):

```python

# src/specify_cli/__init__.py

AI_ASSISTANT_ALIASES = {
    "my": "myai",      # alias → canonical key

}

```

The alias is automatically mentioned in the `--ai` help text, allowing users to type `--ai my` instead of `--ai myai`.

## Step 4: Verify the Integration

After editing the files, verify the integration by running the CLI help:

```bash
specify init --help

```

You should see the new agent listed in the AI assistant options, along with any alias you defined:

```text
AI assistant to use: …, myai, …, or generic (requires --ai-commands-dir).
Use 'my' as an alias for 'myai'.

```

Test the scaffolding behavior:

```bash
specify init myproject --ai myai

# Creates myproject/.myai/ directory structure

```

Test the skill installation:

```bash
specify install-skills myproject myai

# Parses .myai/commands/*.md and generates skills

```

## Step 5: Update Release Scripts (For Upstream Maintainers)

If you are preparing an upstream release, update the packaging scripts so that CI generates the correct template assets.

In [`.github/workflows/scripts/create-release-packages.sh`](https://github.com/github/spec-kit/blob/main/.github/workflows/scripts/create-release-packages.sh), add the agent to the `ALL_AGENTS` array:

```bash
ALL_AGENTS=("claude" "cursor" "myai" "generic")

```

In the PowerShell equivalent (`.github/workflows/scripts/create-release-packages.ps1`), update the `$AllAgents` array:

```powershell
$AllAgents = @("claude", "cursor", "myai", "generic")

```

These arrays drive the creation of agent‑specific zip files (e.g., `spec-kit-template-myai-sh-<ver>.zip`) during the release workflow.

## Summary

- **Register metadata** in `AGENT_CONFIG` ([`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py)) to enable project scaffolding, help‑text generation, and CLI validation.
- **Register command storage** in `CommandRegistrar.AGENT_CONFIGS` ([`src/specify_cli/extensions.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/extensions.py)) to enable skill installation and template parsing.
- **Optionally define an alias** in `AI_ASSISTANT_ALIASES` for shorter command‑line flags.
- **Verify** the integration via `--help`, `init`, and `install-skills` commands.
- **Update release scripts** (`.github/workflows/scripts/create-release-packages.*`) when preparing upstream distributions.

## Frequently Asked Questions

### What happens if I only update AGENT_CONFIG but forget CommandRegistrar.AGENT_CONFIGS?

The CLI will recognize the agent for project initialization and display it in help text, but `specify install-skills` will fail because it cannot locate the command template directory or parse the file format. Both tables must contain matching entries for full functionality.

### Can I use TOML instead of Markdown for command templates?

Yes. In `CommandRegistrar.AGENT_CONFIGS`, set `"format": "toml"` and `"extension": ".toml"`. The `install_ai_skills` function in [`src/specify_cli/extensions.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/extensions.py) parses both formats, extracting front‑matter from Markdown or table headers from TOML to generate the skill definitions.

### How do I add an IDE‑only agent that does not require a CLI binary?

Set `"requires_cli": False` in the `AGENT_CONFIG` entry. When this flag is false, the `check_tool` validation is skipped during `specify check`, allowing the agent to be used for scaffolding and skills even when no executable is present on the host system. This is useful for cloud‑based or IDE‑integrated assistants.

### Where should the command template files actually live inside my project?

Place them in the directory defined by the `"dir"` key in `CommandRegistrar.AGENT_CONFIGS` (e.g., `.myai/commands/`). Each file should use the extension specified (`.md` or `.toml`) and contain valid front‑matter that the parser can convert into skills. These files are typically committed to your repository so that `specify install-skills` can process them on any clone.