# How to Integrate OpenSpec with Other AI Coding Tools

> Learn how to integrate OpenSpec with AI coding tools using its declarative plugin architecture. Generate skill and command files effortlessly for seamless workflow enhancement.

- Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- Tags: how-to-guide
- Published: 2026-06-28

---

**OpenSpec integrates with AI coding assistants through a declarative plugin architecture that generates skill and command files for each tool based on definitions in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts).**

OpenSpec is a flexible framework designed to extend the capabilities of AI coding assistants. If you need to integrate OpenSpec with other tools, the system provides a plug-in architecture that supports dozens of assistants including Claude, Cursor, Gemini CLI, and GitHub Copilot through automatic detection and file generation.

## Understanding the OpenSpec Integration Architecture

The integration operates through three declarative layers that map tool identifiers to file system artifacts. This architecture allows OpenSpec to automatically manage skill files and commands across multiple AI assistants without manual configuration.

### Tool Definitions in config.ts

All supported assistants are enumerated in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts). Each entry in the `AI_TOOLS` configuration defines a **tool ID**, human-readable name, availability status, and the target directory where OpenSpec deposits skill and command files for that assistant. This central configuration acts as the single source of truth for which tools OpenSpec can interface with.

### File Layout and Artifact Generation

When you run `openspec init` or `openspec update`, OpenSpec creates two distinct artifact types per selected tool:

- **Skills**: Markdown files describing the assistant's capabilities (e.g., `openspec-propose`), stored under `<tool-dir>/skills/openspec-*/SKILL.md`
- **Commands**: Slash-command or prompt files that the assistant invokes (e.g., `opsx-propose`), with locations varying by tool as documented in [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)

### Runtime Detection and Wiring

Each tool's `detectionPaths` field tells OpenSpec when a tool is present on the host system. When these paths exist, OpenSpec marks the tool as *detected* and writes the appropriate files, making the assistant immediately aware of the new commands and skills without requiring manual imports.

## Step-by-Step Integration Process

Follow these steps to integrate OpenSpec with your preferred AI coding tools:

1. **Select tools**: Run `openspec init --tools claude,cursor` to generate skill and command skeletons for Claude Code and Cursor.
2. **Choose a profile**: Execute `openspec config profile core` to select the default workflow set (propose, explore, apply, sync, archive).
3. **Apply changes**: Use `openspec update` to write or overwrite per-tool files according to the selected profile and workflow flags.
4. **CI/CD mode**: Run `openspec init --tools all --profile core` for non-interactive setup in automated pipelines, or use `--tools none` to skip tool configuration entirely.

## Initializing OpenSpec for Specific Tools

Use the `openspec init` command with specific flags to target individual assistants or groups:

```bash

# Initialise OpenSpec for a specific set of assistants

openspec init --tools claude,cursor

# Initialise for all supported assistants (useful for a dev box)

openspec init --tools all

# Skip tool configuration entirely (e.g., when only using the internal CLI)

openspec init --tools none

# Override the default profile and add a custom workflow

openspec config profile core
openspec config add-workflow new
openspec update

```

Once initialized, you can invoke the generated commands directly in your AI assistant. For example, in Claude Code:

```bash
/opsx-propose

```

## CI/CD and Automated Integration

For automated pipelines, OpenSpec supports non-interactive configuration through command-line flags:

```bash

# Install only the skill layer for a subset of tools

openspec init --tools github-copilot,gemini --profile core

```

This mode ensures that build agents can provision OpenSpec capabilities without prompting for user input, using the declarative definitions in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts) to determine file placement.

## Extending OpenSpec for Custom Tools

Because the mapping of tool ID to file locations is declarative, adding a new assistant requires only two modifications:

1. Add a new entry to `AI_TOOLS` in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts) specifying the tool ID, name, skill directory, and optional detection paths.
2. Extend the markdown table in [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) with the new tool's skill and command path patterns.

You can also generate skill files manually for custom integrations:

```typescript
// Example: create a custom skill for a new tool "myai"
import { writeFileSync } from 'fs';
const skillPath = '.myai/skills/openspec-propose/SKILL.md';
const skillContent = `# openspec-propose\n\nGenerate a proposal based on the current spec.`;

writeFileSync(skillPath, skillContent);

```

## Key Integration Files

| File | Purpose |
|------|---------|
| [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts) | Central list of AI tool definitions (`AI_TOOLS`) |
| [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) | Human-readable table of per-tool skill and command paths |
| [`docs/cli.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md) | Full CLI reference for init, update, and profile commands |
| [`docs/commands.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md) | Description of generated slash commands and skills |
| [`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js) | Entry point for the `openspec` executable |

## Summary

- OpenSpec uses a declarative plug-in architecture defined in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts) to manage integrations with AI coding assistants.
- The `openspec init` and `openspec update` commands automatically generate skills and commands in tool-specific directories based on the `AI_TOOLS` configuration.
- **Detection paths** automatically enable integrations when target tools are installed on the system, requiring no manual configuration.
- You can extend support to new assistants by adding entries to the `AI_TOOLS` array and updating [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) with path patterns.

## Frequently Asked Questions

### What AI coding tools does OpenSpec support?

OpenSpec supports Claude, Cursor, Gemini CLI, GitHub Copilot, and others. The complete list is defined in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts), with per-tool file locations and path patterns documented in [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md).

### How does OpenSpec detect if a tool is installed?

Each tool entry includes a `detectionPaths` field that specifies file system paths unique to that assistant. When OpenSpec finds these paths on the host system, it marks the tool as available and generates the appropriate skill and command files automatically.

### Can I use OpenSpec in CI/CD pipelines without interactive prompts?

Yes. Use the `--tools` flag with specific tool IDs (or `all`/`none`), combined with `--profile` to specify a workflow set. This enables non-interactive setup suitable for automated pipelines and containerized build environments.

### How do I add support for a custom AI assistant not listed in the config?

Add a new entry to the `AI_TOOLS` array in [`src/core/config.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts) specifying the tool ID, display name, skill directory, and optional detection paths. Then document the skill and command path patterns in [`docs/supported-tools.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) to maintain the human-readable reference.