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

> Integrate custom AI agents into Spec-Kit projects using --ai generic and --ai-commands-dir. Point the CLI to your custom command file directory for seamless support.

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

---

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

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

```

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

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