# How AI Agent Skills Function in Spec-Kit: A Complete Guide to the `--ai-skills` Flag

> Discover how AI agent skills work in Spec-Kit and install them easily with the --ai-skills flag. Learn to leverage Prompt.MD templates for enhanced agent functionality.

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

---

**AI agent skills in Spec-Kit are Prompt.MD command templates transformed into the agentskills.io specification format, installed automatically when you append the `--ai-skills` flag to the `specify init` command.**

Spec-Kit, the GitHub repository for standardized project initialization, converts bundled **Prompt.MD** command templates into **agent skills** that follow the **agentskills.io** specification. When you initialize a project with the `--ai-skills` flag, the CLI discovers these templates and converts them into structured [`SKILL.md`](https://github.com/github/spec-kit/blob/main/SKILL.md) files that compatible AI agents can consume immediately.

## What Are AI Agent Skills?

AI agent skills are pre-packaged command prompts distributed with Spec-Kit that have been transformed into a standardized layout. Rather than distributing raw templates, Spec-Kit rewrites them as [`SKILL.md`](https://github.com/github/spec-kit/blob/main/SKILL.md) files containing required front-matter fields—`name`, `description`, `compatibility`, and `metadata`—followed by the original prompt body. This conversion allows any agentskills.io-compatible tool to discover and execute these capabilities. The installation process is **additive**, meaning existing skill directories remain untouched and existing [`SKILL.md`](https://github.com/github/spec-kit/blob/main/SKILL.md) files are never overwritten.

## How the `--ai-skills` Flag Works

The `--ai-skills` flag is exposed as a boolean option on the `init` command. According to the source code in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) (lines 2121-2124), the CLI first validates that an `--ai` agent has also been provided; otherwise, it aborts with an error. If validation passes, the flag triggers the `install_ai_skills()` function after the project template has been extracted (lines 1490-1494).

## The Skill Installation Pipeline

The core installation logic resides in `install_ai_skills()` within [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) (lines 1090-1250). The pipeline executes three distinct phases to convert command templates into agent-ready skills.

### 1. Determining the Skills Directory

The helper function `_get_skills_dir()` (lines 1072-1086) determines the correct destination folder based on the selected agent type. For Claude Code, it returns `.claude/skills`; for other agents, it may return the generic `specify/skills` folder. This ensures skills are installed to locations where the target agent expects to find them.

### 2. Discovering Command Templates

The function searches for extracted `*.md` files in the agent-specific **commands** subdirectory, such as `.claude/commands` or `.gemini/commands` (lines 1109-1115). When running Spec-Kit from a source checkout where these directories might be missing, the code falls back to the repository-wide `templates/commands` folder (lines 1117-1124), ensuring templates remain discoverable in development environments.

### 3. Converting Templates to SKILL.md

For each template discovered, the code performs the following transformations (lines 1119-1238):

- **Parses** optional YAML front-matter from the original Prompt.MD
- **Builds** a skill name following the `speckit-<command>` pattern
- **Enriches** the description using the internal `SKILL_DESCRIPTIONS` lookup table
- **Writes** a [`SKILL.md`](https://github.com/github/spec-kit/blob/main/SKILL.md) file containing the required front-matter header followed by the original prompt body

## Installing Skills During Project Initialization

Use the `--ai-skills` flag alongside `--ai` to automatically populate your agent's skills folder during project setup.

Initialize a new project with Claude Code skills:

```bash
specify init my-project --ai claude --ai-skills --script sh --no-git

```

Initialize in the current directory with Gemini and install its skills:

```bash
specify init . --ai gemini --ai-skills --script sh

```

For generic or unsupported agents, you must also provide the commands directory:

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

```

When the command completes, you will see a concise summary such as:

```

✓ Installed 12 agent skills to .claude/skills/

```

If skills were already present, the output reports the skip count instead of overwriting existing files.

## Summary

- AI agent skills follow the **agentskills.io** specification and originate from Prompt.MD templates stored in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py)
- The `--ai-skills` flag requires an accompanying `--ai` argument and triggers `install_ai_skills()` after template extraction (lines 1490-1494)
- Skills install to agent-specific directories determined by `_get_skills_dir()` (lines 1072-1086), such as `.claude/skills` or `.gemini/skills`
- The installation process is **non-destructive**, skipping existing [`SKILL.md`](https://github.com/github/spec-kit/blob/main/SKILL.md) files rather than overwriting them (lines 1119-1238)
- Fallback logic in lines 1117-1124 ensures templates are discoverable from the repository-wide `templates/commands/` folder when running from source

## Frequently Asked Questions

### What happens if I run `--ai-skills` without specifying an AI agent?

The CLI validates flag dependencies in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) (lines 2121-2124) and aborts with an error if the `--ai` argument is missing. You must pair `--ai-skills` with a specific agent type such as `claude` or `gemini` so the system knows which skills directory structure to create.

### Where are the generated skill files stored?

The `_get_skills_dir()` function determines the location based on the agent type, creating directories like `.claude/skills` for Claude Code or `specify/skills` for generic configurations, as implemented in lines 1072-1086 of the CLI module.

### Will running `--ai-skills` overwrite my existing skills?

No. The installation process is additive. According to lines 1119-1238 in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py), the function checks for existing [`SKILL.md`](https://github.com/github/spec-kit/blob/main/SKILL.md) files and skips any skills that are already present, ensuring your custom modifications remain intact.

### Can I use `--ai-skills` with unsupported or custom AI agents?

Yes. For agents not officially supported, you must provide the `--ai-commands-dir` flag pointing to your command templates directory. The system will then use these templates to generate skills in the generic skills folder structure, falling back to repository-wide templates only if the custom directory is unavailable.