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

> Configure custom agent command directories with --ai-commands-dir for unsupported agents. Point the specify CLI to your custom directory with the --ai generic flag.

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

---

**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`](https://github.com/github/spec-kit/blob/main/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:

```python

# 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](https://github.com/github/spec-kit/blob/main/src/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`](https://github.com/github/spec-kit/blob/main/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.

```python

# 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](https://github.com/github/spec-kit/blob/main/src/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:

```python
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](https://github.com/github/spec-kit/blob/main/src/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/github/spec-kit/blob/main/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`](https://github.com/github/spec-kit/blob/main/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.