How to Configure Custom Agent Command Directories with `--ai-commands-dir` for Unsupported Agents

Use the --ai-commands-dir flag with --ai generic to point the specify CLI to a custom directory containing your unsupported agent's command files.

The specify CLI from the github/spec-kit repository supports a built-in set of AI assistants with predefined folder layouts. When working with an unsupported or "bring-your-own" agent, you must explicitly configure custom agent command directories using the --ai-commands-dir flag to tell the CLI where your agent's command files reside.

Understanding the Generic Agent Configuration

The CLI maintains an internal AGENT_CONFIG dictionary in src/specify_cli/__init__.py that defines supported agents. For unsupported agents, the CLI provides a generic agent entry whose folder value is None by design:

# src/specify_cli/__init__.py – generic agent definition

"generic": {
    "name": "Generic (bring your own agent)",
    "folder": None,                     # ← set dynamically via --ai-commands-dir

    "commands_subdir": "commands",
    "install_url": None,
    "requires_cli": False,
},

Source: specify_cli/init.py#L54-L60

At runtime, the CLI populates this folder field with the path supplied to --ai-commands-dir, allowing the generic agent to locate its command files.

Validating the --ai-commands-dir Flag

During specify init, the CLI enforces strict validation rules to ensure --ai-commands-dir is used correctly. The validation logic in src/specify_cli/__init__.py implements two critical checks:

1. Required for generic agents: If the selected assistant is generic, --ai-commands-dir must be present.
2. Rejected for supported agents: For any other assistant, the flag is rejected because the layout is already known.

# src/specify_cli/__init__.py – validation logic

if selected_ai == "generic":
    if not ai_commands_dir:
        console.print("[red]Error:[/red] --ai-commands-dir is required when using --ai generic")
        console.print("[dim]Example: specify init my-project --ai generic --ai-commands-dir .myagent/commands/[/dim]")
        raise typer.Exit(1)
elif ai_commands_dir:
    console.print(f"[red]Error:[/red] --ai-commands-dir can only be used with --ai generic (not '{selected_ai}')")
    raise typer.Exit(1)

Source: specify_cli/init.py#L1287-L1296

Protecting Against Flag Consumption Errors

The CLI includes safeguards against accidental flag consumption. If you supply --ai-commands-dir without an accompanying path value, the next token might be interpreted as the directory path, potentially consuming another flag.

The validation logic detects when the provided value starts with -- and raises an explicit error:

if ai_commands_dir and ai_commands_dir.startswith("--"):
    console.print(f"[red]Error:[/red] Invalid value for --ai-commands-dir: '{ai_commands_dir}'")
    console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai-commands-dir?")
    console.print("[yellow]Example:[/yellow] specify init --ai generic --ai-commands-dir .myagent/commands/")
    raise typer.Exit(1)

Source: specify_cli/init.py#L1300-L1304

Practical Examples

Initializing a Project with a Custom Agent

To use an unsupported agent, specify generic as the AI assistant and provide the path to your agent's command directory:

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

Common Error: Missing Directory Value

If you omit the directory path, the CLI detects the flag consumption and provides a helpful error message:

specify init my-project --ai generic --ai-commands-dir --here

Output:

Error: Invalid value for --ai-commands-dir: '--here'
Hint: Did you forget to provide a value for --ai-commands-dir?
Example: specify init --ai generic --ai-commands-dir .myagent/commands/

Common Error: Using the Flag with Supported Agents

The --ai-commands-dir flag is strictly for generic agents. Using it with supported agents like claude or gemini results in an error:

specify init my-project --ai claude --ai-commands-dir .myagent/commands/

Output:

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

Summary

• The --ai-commands-dir flag enables custom agent command directories for unsupported AI assistants in the specify CLI.
• Use --ai generic combined with --ai-commands-dir <path> to point the CLI to your agent's command files.
• The CLI validates that --ai-commands-dir is only used with generic agents and protects against accidental flag consumption.
• Configuration details are defined in src/specify_cli/__init__.py within the AGENT_CONFIG dictionary.

Frequently Asked Questions

What happens if I use --ai-commands-dir with a supported agent like Claude or Gemini?

The CLI rejects the command and displays an error message stating that --ai-commands-dir can only be used with --ai generic. Supported agents have predefined folder layouts in AGENT_CONFIG, so custom directories are not permitted.

Can I use --ai-commands-dir without specifying --ai generic?

No. The CLI requires the --ai generic flag when using --ai-commands-dir. If you omit --ai generic, the validation logic in src/specify_cli/__init__.py raises an error indicating that the directory flag is required for generic agents.

What directory structure should I use for my custom agent commands?

The generic agent expects a commands/ subdirectory within the path you provide to --ai-commands-dir. According to the AGENT_CONFIG definition, the commands_subdir field is set to "commands", so organize your agent's command files accordingly.

How does the CLI prevent me from accidentally using another flag as the directory path?

The CLI checks if the value provided to --ai-commands-dir starts with --. If it does, the CLI prints an explicit error message suggesting you may have forgotten to provide a value, along with a usage example. This prevents flags like --here from being interpreted as directory paths.

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