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

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 and the CommandRegistrar.AGENT_CONFIGS dictionary in 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, 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, 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 and add a new entry to the AGENT_CONFIG dictionary. The key must match the exact CLI executable name.

# 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 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.

# 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:

# 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:

specify init --help

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

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

Test the scaffolding behavior:

specify init myproject --ai myai

# Creates myproject/.myai/ directory structure

Test the skill installation:

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, add the agent to the ALL_AGENTS array:

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

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

$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) to enable project scaffolding, help‑text generation, and CLI validation.
• Register command storage in CommandRegistrar.AGENT_CONFIGS (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}