How Generic Agent Support Works with `--ai-commands-dir` for Custom Agents in Spec-Kit

Use the --ai generic flag combined with --ai-commands-dir to integrate custom AI agents into Spec-Kit projects by pointing the CLI to your own command file directory.

The Spec-Kit CLI enables a bring-your-own-agent workflow through its init command, allowing developers to integrate proprietary or experimental AI assistants alongside built-in options like Claude or ChatGPT. By selecting the special generic agent and supplying a directory path via --ai-commands-dir, you instruct the tool to load command definitions and skill templates from your local filesystem rather than the bundled defaults. This architecture delegates folder resolution to runtime while maintaining consistent internal APIs for command discovery and skill installation.

The Generic Placeholder in AGENT_CONFIG

The foundation of custom agent support resides in the AGENT_CONFIG dictionary defined in src/specify_cli/__init__.py. Within this configuration, the generic entry serves as a runtime placeholder with two critical properties:

• folder: Initialized to None, indicating the directory path will be supplied dynamically at runtime rather than hardcoded.
• commands_subdir: Defaults to "commands", defining the expected subdirectory structure within your custom path where agent-specific command files reside.

This configuration signals to the CLI that the generic agent requires external path resolution before any file operations can proceed.

CLI Option Definition and Help Text

The init command exposes the --ai-commands-dir option to capture your custom agent's root directory. As defined in src/specify_cli/__init__.py, the option includes the help text: "Directory for agent command files (required with --ai generic, e.g. .myagent/commands/)".

The help text for --ai is constructed dynamically from AGENT_CONFIG, automatically appending "or generic (requires --ai-commands-dir)" to the list of available agents. This ensures documentation stays synchronized with runtime validation rules.

Validation Logic in the Init Command

When executing specify init, the CLI enforces strict validation rules regarding --ai-commands-dir based on the selected agent:

1. Mandatory for generic: If selected_ai equals "generic", the code explicitly checks for the presence of ai_commands_dir. When missing, the CLI aborts with the error:

   
   [red]Error:[/red] --ai-commands-dir is required when using --ai generic
   

2. Forbidden for built-ins: If any non-generic agent is selected (e.g., claude), providing --ai-commands-dir triggers an error:

   
   [red]Error:[/red] --ai-commands-dir can only be used with --ai generic (not 'claude')
   

These validations reside in the argument parsing section of the init command implementation.

Dynamic Folder Assignment and Command Resolution

Upon successful validation, the CLI assigns your supplied path to the generic agent's folder property. This dynamic assignment enables all downstream operations—such as skill installation and command template copying—to function identically for custom agents as they do for built-in ones.

The code treats agent_config["folder"] as the root directory for file operations, effectively overlaying your custom command structure onto the standard agent workflow. Because commands_subdir remains "commands", the CLI expects to find executable skill definitions at {ai_commands_dir}/commands/.

Practical Usage Examples

Initialize a project with a custom agent stored in your filesystem:

specify init my-project \
    --ai generic \
    --ai-commands-dir .myagent/commands/

For current-directory initialization using the --here flag:

specify init . \
    --ai generic \
    --ai-commands-dir .myagent/commands/ \
    --here

Expected Directory Structure

Your custom agent directory should follow the standard layout:

.myagent/
└── commands/
    ├── skill-one.yaml
    ├── skill-two.yaml
    └── ...

Summary

• AGENT_CONFIG defines a generic entry with folder=None to enable runtime path assignment.
• --ai-commands-dir is required exclusively when --ai generic is specified.
• Validation logic in src/specify_cli/__init__.py prevents mismatched flag usage.
• The supplied directory path becomes the root for command discovery and skill installation.
• Built-in agents reject --ai-commands-dir to prevent configuration collisions.

Frequently Asked Questions

What is the generic agent in Spec-Kit?

The generic agent is a configuration placeholder in the Spec-Kit CLI that enables users to integrate custom AI assistants not bundled with the tool. Unlike built-in agents such as Claude or GPT-4 that have hardcoded paths in AGENT_CONFIG, the generic agent relies on runtime-supplied directory paths via --ai-commands-dir to locate command definitions and skill templates.

Why is --ai-commands-dir required with --ai generic?

The --ai-commands-dir flag is required because the generic agent configuration lacks a predefined folder path in AGENT_CONFIG. Without this directory pointer, the CLI cannot locate the command files necessary for skill installation and project initialization. This requirement ensures the tool has a valid filesystem root for all subsequent file operations.

Can I use --ai-commands-dir with built-in agents like Claude or ChatGPT?

No. The validation logic explicitly rejects --ai-commands-dir when used with non-generic agents. Built-in agents have fixed directory structures defined in AGENT_CONFIG, and supplying a custom path would conflict with these predefined locations. Attempting to combine the flag with built-in agents results in an error message indicating the flag is reserved for generic use only.

Where should I store my custom agent command files?

Store your custom agent files in a dedicated directory following the {agent-name}/commands/ convention, then reference the parent directory with --ai-commands-dir. For example, if your commands reside in .myagent/commands/, pass --ai-commands-dir .myagent/commands/ to the CLI. The tool expects the commands subdirectory to contain YAML or executable skill definitions.

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