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

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 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 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 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 (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 (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 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:

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

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

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

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

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
• 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 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 (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, the function checks for existing 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.

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