# https://github.com/moatazhamada/ai-omni-skills Project Manual

Generated at: 2026-06-22 06:54:20 UTC

## Table of Contents

- [Omni Skills Overview and Architecture](#page-1)
- [CLI Commands, Workflows, and Setup](#page-2)
- [MCP Server and Supported AI Tools](#page-3)
- [Skills Storage, Sync Engine, and Verification](#page-4)

<a id='page-1'></a>

## Omni Skills Overview and Architecture

### Related Pages

Related topics: [CLI Commands, Workflows, and Setup](#page-2), [MCP Server and Supported AI Tools](#page-3), [Skills Storage, Sync Engine, and Verification](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md)
- [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/package.json)
- [RELEASE_NOTES.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/RELEASE_NOTES.md)
- [INDEX.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/INDEX.md)
- [lib/setup.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/setup.js)
- [lib/discover.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/discover.js)
- [examples/workflows/feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/feature-dev/WORKFLOW.md)
- [examples/workflows/advanced-feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/advanced-feature-dev/WORKFLOW.md)
- [examples/workflows/release-prep/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/release-prep/WORKFLOW.md)
- [examples/workflows/debug-trace/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/debug-trace/WORKFLOW.md)
- [examples/example-skill/SKILL.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/example-skill/SKILL.md)
</details>

# Omni Skills Overview and Architecture

## Purpose and Scope

Omni Skills is a CLI toolkit and MCP (Model Context Protocol) server designed to unify AI agent skills and instruction files across the many AI coding tools a developer may use. It addresses the fragmentation problem where users accumulate skills in separate directories (`.claude/`, `.kimi/`, `.codex/`, `.gemini/`, `.cursor/`, `.kilocode/`, etc.) and watch them drift out of sync. Source: [README.md:1-40]()

The toolkit is intentionally **code only** — it ships no skills or instruction files. Users store their own skills in private repositories that they control, and Omni Skills syncs those into every supported tool. Source: [CONTRIBUTING.md:35-40]()

The latest published release is **Omni Skills v1.2.21**, distributed via npm with provenance. Source: [CHANGELOG.md:1-5]()

## High-Level Architecture

Omni Skills operates as a single canonical store with bidirectional sync into each AI tool's native configuration location. The architecture is organized around three portability tiers:

| Tier | Mechanism | Examples |
|------|-----------|----------|
| **A** | Symlinks + local MCP server | `SKILL.md` skills, shared instructions, `list_skills` / `read_skill` MCP tools |
| **B** | Canonical hooks transpiled into each tool's native format | Tool-specific hook files |
| **C** | Symlinks from config repo to per-tool paths | Other miscellaneous assets |

Source: [README.md:80-95]()

```mermaid
flowchart LR
    A[Private Skills Repo<br/>canonical store] --> B[omni-skills CLI]
    B --> C1[Claude]
    B --> C2[Codex]
    B --> C3[Kimi]
    B --> C4[Gemini]
    B --> C5[Cursor]
    B --> C6[Cline]
    B --> C7[Zed]
    B --> CN[...26 tools]
    A --> D[MCP Server]
    D --> E1[list_skills]
    D --> E2[read_skill]
    E1 --> C1
    E1 --> C2
    E2 --> C1
    E2 --> C2
```

The `omni-skills setup` command reads tool definitions from `lib/setup.js`, which declares for each tool its `instructionFile`, `instructionMode`, `skillsDir`, `mcp` config (file path and format), and `hooks` config. Source: [lib/setup.js:1-40]()

## Core Components

### CLI Commands

The CLI exposes 11 commands that drive the entire sync, discovery, and health-check workflow:

- `sync <tool|all>` — mirror canonical store into a target tool
- `check [--move] [--dry-run]` — find orphaned skills and dangling symlinks
- `classify [path] [--depth=N] [--dry-run]` — scan for instruction files and detect sensitive content
- `discover` — scan the entire system for AI tools, instruction files, and skill directories
- `setup` — auto-detect tools, suggest cleanup, generate config
- `doctor` — health check on symlinks, config, indexes, and skill counts
- `report [--enhance]` — usage statistics and heuristic improvement tips
- `init [--dry-run]` — interactive setup that scans, classifies, routes, and wires
- `index` — generate the skills index
- `mcp` — start the MCP server
- `help`

Source: [README.md:130-160]()

### Discovery and Tool Detection

`lib/discover.js` defines `SKILL_DIR_NAMES` (e.g., `skills`, `.skills`, `ai-skills`, `agent-skills`) and a comprehensive list of instruction file names (e.g., `AGENTS.md`, `CLAUDE.md`, `CONVENTIONS.md`, `.github/copilot-instructions.md`). The `findToolDirs()` function walks `AI_TOOL_DIRS` and reports any installed tool directory it finds. Source: [lib/discover.js:1-50]()

### MCP Server

The MCP server exposes two capabilities to any MCP-compatible AI tool:

- `list_skills` — returns metadata (name, description) for all discovered skills
- `read_skill` — loads the full body of a named skill before the agent acts

Source: [README.md:100-120]()

### Workflows

Workflows are named YAML files that chain skills into repeatable sequences. They live in the user's private repository under `workflows/`. Source: [README.md:175-180]()

The simple `release-prep` workflow chains three skills linearly: `lint-and-validate` → `testing-patterns` → `commit-suggest`. Source: [examples/workflows/release-prep/WORKFLOW.md:1-12]()

The advanced `advanced-feature-dev` workflow demonstrates the full step-type vocabulary:

| Step Type | Syntax | Behavior |
|-----------|--------|----------|
| Skill | `skill: name` | Load and execute one skill |
| Goal | `goal: "..."` | Success condition for the step |
| Retry | `max_retries: 3` | Auto-retry on failure |
| Loop | `loop: { until, max_iterations, steps }` | Repeat until condition met |
| Condition | `condition: { check, then, else }` | Branch based on a check |
| Parallel | `parallel: { branches: [...] }` | Run branches concurrently |

Source: [README.md:200-220](), [examples/workflows/advanced-feature-dev/WORKFLOW.md:1-50]()

## Verification, Testing, and Maintenance

A 24-check verification suite lives in `verify.js` and validates config loading, skill paths, skill file integrity, `SHARED.md` presence, instruction symlinks, per-tool skills directories, and MCP configurations. Source: [CHANGELOG.md:15-20](), [README.md:280-295]()

The project ships 14 unit tests using Node's built-in test runner (no extra dependencies), and CI runs both `npm test` and `node verify.js` on every push. Source: [CHANGELOG.md:20-22](), [CONTRIBUTING.md:25-30]()

A scheduled cron job invokes `omni-skills doctor` weekly (Sundays at 9:17 AM) to catch drift between the canonical store and the per-tool mirrors. Source: [README.md:265-275]()

## Use Cases and Common Patterns

Three example workflows illustrate the breadth of supported patterns:

- **Feature development** — refine requirements, write a spec, plan, implement, commit. Source: [examples/workflows/feature-dev/WORKFLOW.md:1-15]()
- **Release preparation** — lint, test, and commit before release. Source: [examples/workflows/release-prep/WORKFLOW.md:1-12]()
- **Debug and trace** — systematic root-cause tracing, regression test, descriptive commit. Source: [examples/workflows/debug-trace/WORKFLOW.md:1-12]()

A minimal `example-skill/SKILL.md` is provided as a copy-and-customize template. Source: [examples/example-skill/SKILL.md:1-5]()

## See Also

- [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md) — version history and feature additions
- [CONTRIBUTING.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CONTRIBUTING.md) — contribution guidelines and what is accepted
- [RELEASE_NOTES.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/RELEASE_NOTES.md) — release notes for v1.0.0 and later
- [GitHub Discussions](https://github.com/moatazhamada/ai-omni-skills/discussions) — community Q&A and feature ideas
- [GitHub Issues](https://github.com/moatazhamada/ai-omni-skills/issues) — bug reports and feature requests

---

<a id='page-2'></a>

## CLI Commands, Workflows, and Setup

### Related Pages

Related topics: [Omni Skills Overview and Architecture](#page-1), [Skills Storage, Sync Engine, and Verification](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [cli.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/cli.js)
- [lib/setup.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/setup.js)
- [lib/init.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/init.js)
- [lib/workflows.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/workflows.js)
- [lib/check.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/check.js)
- [lib/classify.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/classify.js)
- [lib/discover.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/discover.js)
- [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md)
- [examples/workflows/feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/feature-dev/WORKFLOW.md)
- [examples/workflows/advanced-feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/advanced-feature-dev/WORKFLOW.md)
- [examples/workflows/release-prep/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/release-prep/WORKFLOW.md)
- [examples/workflows/debug-trace/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/debug-trace/WORKFLOW.md)
</details>

# CLI Commands, Workflows, and Setup

## Overview

Omni Skills ships as a Node CLI (`omni-skills`) that unifies skills, instruction files, and MCP configuration across 26 supported AI tools. The CLI is the primary entry point and exposes commands for setup, discovery, classification, health checks, and workflow execution. The toolkit itself is **code only** — your skills live in one or more private repositories that the CLI discovers, classifies, and wires into every AI tool you use. Source: [README.md:1-40]()

The CLI surface is intentionally small. After install (`npm install -g ai-omni-skills`), users run a setup wizard, then drive ongoing maintenance with a handful of commands. Workflows provide reusable, multi-step pipelines that chain skills together with loops, conditions, and parallel branches.

---

## CLI Command Surface

The CLI exposes 11 top-level commands. Source: [CHANGELOG.md:30-50]() Each command maps to a module under `lib/`:

| Command | Module | Purpose |
|---------|--------|---------|
| `setup` | `lib/setup.js` | First-run wizard that writes `~/.config/skills/config.json` |
| `sync` | `lib/sync.js` | Wire skills, instructions, MCP, and hooks into every AI tool |
| `doctor` | `lib/doctor.js` | 24-check verification suite for tool wiring and symlink health |
| `discover` | `lib/discover.js` | Scan the filesystem for tool dirs and instruction files |
| `classify` | `lib/classify.js` | Sort instruction files into the canonical store |
| `check` | `lib/check.js` | Detect orphaned or duplicate skills; `--move` rescues them |
| `report` | — | Summarize portfolio state |
| `index` | — | Generate per-tool indexes from the canonical store |
| `init` | `lib/init.js` | Initialize a new project with skills scaffolding |
| `mcp` | — | Register the local MCP server with AI tools |
| `help` | — | Print usage |

The pattern is: **discover → classify → check → setup → sync → doctor**. Running `setup` walks the user through this path interactively, suggesting cleanup actions based on what was discovered. Source: [lib/setup.js:150-220]()

```mermaid
flowchart LR
    A[discover] --> B[classify]
    B --> C[check --move]
    C --> D[setup]
    D --> E[sync all]
    E --> F[doctor]
    F -- weekly cron --> F
```

---

## Setup Wizard

`omni-skills setup` is the entry point for new users. It scans the filesystem for installed AI tools, finds their skill directories, and writes a canonical config at `~/.config/skills/config.json`. Source: [lib/setup.js:180-220]() The wizard supports 26 AI tools including Claude, Codex, Kimi, Gemini, Cursor, Kilocode, OpenCode, Cline, Roo, Windsurf, Zed, Aider, Continue, Tabby, PearAI, Void, Supermaven, Augment, Codeium, Copilot, Junie, AI Assistant, Claude Desktop, Devin, Factory Droid, and Z.AI (GLM 5.2). Source: [CHANGELOG.md:36-40]()

Each tool entry in `setup.js` defines four optional slots:

- `instructionFile` — path to the tool's instruction/rule file
- `skillsDir` — directory where the tool reads skills (string or array)
- `mcp` — MCP config file path and format (`mcpServers`, `codex-toml`, `opencode`, `zed`, etc.)
- `hooks` — hook file path and format

For example, `kimi` declares `skillsDir: ["~/.kimi/skills", "~/.kimi-code/skills"]` — an array to handle Kimi's dual directory layout. Source: [lib/setup.js:12-22]() Original native skills are backed up to `.skills-bak/` before symlink rewiring. Source: [CHANGELOG.md:64-68]()

After setup completes, the wizard prints next steps: `skills classify`, `skills check --move`, `skills index`, `skills sync all`, and `skills doctor`. Source: [lib/setup.js:200-220]()

---

## Workflows

Workflows are YAML files under `workflows/` that compose skills into reusable pipelines. They live in your private repo, not in this toolkit. Source: [README.md:180-220]()

The schema supports six step types:

| Type | Syntax | Behavior |
|------|--------|----------|
| **Skill** | `skill: name` | Load and execute one skill |
| **Goal** | `goal: "..."` | Success condition for the step |
| **Retry** | `max_retries: N` | Retry on failure |
| **Loop** | `loop: { until, max_iterations, steps }` | Repeat until condition met |
| **Condition** | `condition: { check, then, else }` | Branch on a check |
| **Parallel** | `parallel: { branches: [...] }` | Run branches concurrently |

Source: [README.md:200-230]()

Four example workflows ship in `examples/workflows/`:

- **`feature-dev`** — linear pipeline: `refine-requests → speckit-specify → speckit-plan → speckit-implement → speckit-git-commit`. Source: [examples/workflows/feature-dev/WORKFLOW.md:1-15]()
- **`advanced-feature-dev`** — adds a loop for spec refinement, a condition branching between `speckit-plan` and `speckit-tasks`, and a parallel block running `lint-and-validate`, `testing-patterns`, and `speckit-analyze` concurrently. Source: [examples/workflows/advanced-feature-dev/WORKFLOW.md:1-60]()
- **`release-prep`** — `lint-and-validate → testing-patterns → commit-suggest`. Source: [examples/workflows/release-prep/WORKFLOW.md:1-12]()
- **`debug-trace`** — `systematic-debugging → testing-patterns → commit-suggest`. Source: [examples/workflows/debug-trace/WORKFLOW.md:1-12]()

The `advanced-feature-dev` workflow illustrates the full expressiveness: a `max_retries: 2` on refinement, a loop with `until: "user says approved"`, a condition that skips heavy planning for simple specs, and a parallel block for quality gates. Source: [examples/workflows/advanced-feature-dev/WORKFLOW.md:8-58]()

---

## Common Failure Modes

Three patterns recur in support and issues:

1. **Stale duplicate instruction files.** Before setup, users often have copies of `AGENTS.md`, `GEMINI.md`, `CLAUDE.md` scattered across project roots. `setup` counts and reports them; the project author's setup deleted 77 such files. Source: [README.md:280-300]()
2. **Orphaned skills in legacy dirs.** Kimi, in particular, accumulated skills in `~/.kimi/skills/` that were not tracked by the canonical store. `check --move` rescues them; the example setup moved 15 orphaned skills. Source: [README.md:290-310]()
3. **Symlink drift after tool reinstall.** When an AI tool is reinstalled, its skill directory is recreated empty, breaking symlinks from the canonical store. `doctor` flags expected-but-missing directories (Claude and OpenCode show ✓ when the link is correct). Source: [CHANGELOG.md:70-74]()

A weekly cron running `omni-skills doctor` (configurable via the toolkit's health-check hook) catches drift before it breaks a session. Source: [CHANGELOG.md:42-46]()

---

## See Also

- [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md) — full feature tour with personal stats
- [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md) — version history including v1.2.21
- [CONTRIBUTING.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CONTRIBUTING.md) — what to contribute (and what not to)
- [examples/example-skill/SKILL.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/example-skill/SKILL.md) — minimal skill template

---

<a id='page-3'></a>

## MCP Server and Supported AI Tools

### Related Pages

Related topics: [Omni Skills Overview and Architecture](#page-1), [Skills Storage, Sync Engine, and Verification](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [config.example.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/config.example.json)
- [lib/setup.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/setup.js)
- [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js)
- [lib/discover.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/discover.js)
- [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md)
- [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md)
- [RELEASE_NOTES.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/RELEASE_NOTES.md)
- [examples/workflows/feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/feature-dev/WORKFLOW.md)
- [examples/workflows/advanced-feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/advanced-feature-dev/WORKFLOW.md)
</details>

# MCP Server and Supported AI Tools

Omni Skills ships a dual-purpose runtime: a CLI toolkit that unifies your private skills and instructions, and an embedded MCP (Model Context Protocol) server that exposes those unified skills to every AI coding tool that speaks MCP. This page covers the MCP server surface, the catalog of supported tools, and how configuration varies between them.

## Purpose and Scope

The MCP server solves a single recurring problem: skills you curate in a private repository are useless if no AI tool can discover them. By running a local MCP server, Omni Skills lets any compatible agent (Claude Code, Cursor, Cline, Zed, Codex, and more) call two operations — `list_skills` and `read_skill` — without copying or symlinking individual skill files into every tool's native directory.

The server is started by the `mcp` CLI command and is also launched implicitly by every `sync` run, which rewrites each tool's MCP configuration to point at the local `cli.js` entry point. Per the CHANGELOG, the server identifier was renamed from `skills` to `omni-skills` in v1.2.2 to avoid name collisions with native tooling. Source: [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md).

Scope is intentionally narrow:
- It does not store skills itself — those live in a user-owned private repo.
- It does not manage conversation state, prompts, or tool calls beyond skill retrieval.
- It does not require network access; everything resolves against local paths.

## MCP Configuration Variants

Each supported AI tool has a different native configuration format. The sync engine handles this by emitting the right syntax per tool. Source: [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js) inspects `mcp.format` and dispatches to one of several writers.

| Format token | Used by | What gets written |
|--------------|---------|-------------------|
| `mcpServers` | Kimi, Gemini, Cursor, Cline, Roo, Windsurf, PearAI | A `mcpServers` JSON object keyed by `omni-skills` |
| `codex-toml` | Codex | A managed `[mcp_servers.omni-skills]` TOML block wrapped in sentinel comments |
| `opencode` | OpenCode | A `mcp` key inside `opencode.jsonc` |
| `zed` | Zed | A `context_servers` entry inside `settings.json` |
| `gemini-json` | Gemini | A hooks block appended next to MCP settings |

The sync layer also injects two environment variables so the server can locate the canonical skills store: `MCP_SKILL_PATHS` (comma-separated absolute paths) and `SKILLS_CONFIG` (the resolved config file location). Source: [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js).

A truncated view of how `codex-toml` output looks:

```toml
# >>> skills-mcp >>>
[mcp_servers.omni-skills]
command = "node"
args = [".../cli.js", "mcp"]
env = { MCP_SKILL_PATHS = "/home/u/my-skills-private", SKILLS_CONFIG = "/home/u/.omni-skills/config.json" }
# <<< skills-mcp <<<
```

The sentinel comments matter: they let `sync` re-run idempotently without duplicating the block.

## Supported AI Tools Catalog

The release notes advertise configuration support for 26 AI tools. Source: [RELEASE_NOTES.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/RELEASE_NOTES.md). Each entry in `config.example.json` defines four fields: `instructionFile`, `instructionMode`, `skillsDir`, `mcp`, and `hooks`. Source: [config.example.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/config.example.json).

| Tool | Instruction file | Skills directory | MCP format |
|------|------------------|------------------|------------|
| Claude | `~/.claude/CLAUDE.md` | `~/.claude/skills` | native symlink |
| Codex | `~/.codex/AGENTS.md` | `~/.codex/skills` | `codex-toml` |
| Kimi | `~/.kimi/AGENTS.md` | `~/.kimi/skills` and `~/.kimi-code/skills` | `mcpServers` |
| Gemini | `~/.gemini/GEMINI.md` | — | `mcpServers` |
| Cursor | `~/.cursor/rules/shared-skills.md` | — | `mcpServers` |
| OpenCode | `~/.config/opencode/opencode.jsonc` | — | `opencode` |
| Cline | `~/.cline/rules.md` | `~/.cline/skills` | `mcpServers` |
| Roo | `~/.roo/rules.md` | `~/.roo/skills` | `mcpServers` |
| Windsurf | `~/.windsurf/rules.md` | — | `mcpServers` |
| Zed | `~/.config/zed/settings.json` | — | `zed` |
| Tabby | `~/.tabby/config.toml` | — | none |
| PearAI | `~/.pearai/config.json` | — | none |
| Void | `~/.void/config.json` | — | — |

Two special cases are worth highlighting:

- **Kimi** uses an array of two skills directories (`~/.kimi/skills` and `~/.kimi-code/skills`). The v1.2.2 fix taught `wireSkillsDir` to accept arrays so both targets receive synced skills, with original native skills backed up to `.skills-bak/`. Source: [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md).
- **Z.AI (GLM 5.2)** is not a native tool entry — it is wired by reusing Claude Code, Cline, or Zed with a GLM Coding Plan key, or by installing the `glm-copilot` extension for VS Code Copilot. Source: [RELEASE_NOTES.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/RELEASE_NOTES.md).

Tools with no MCP entry (Tabby, PearAI, Void) only receive instruction file and/or skills directory wiring; they cannot call `list_skills` / `read_skill` over MCP.

## Workflow Integration

The MCP server is the runtime substrate that makes workflows portable. A `WORKFLOW.md` file references skill names (e.g. `refine-requests`, `speckit-specify`) and the server resolves them at execution time from the canonical store. Source: [examples/workflows/feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/feature-dev/WORKFLOW.md) and [examples/workflows/advanced-feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/advanced-feature-dev/WORKFLOW.md).

The advanced workflow example demonstrates step types beyond plain skill invocation: loops with `until` conditions, conditional branches (`condition.check`), parallel branches (`parallel.branches`), per-step goals, and retry limits. Because these are just YAML descriptors, the same workflow can be triggered from any AI tool that reaches the MCP server — there is no tool-specific workflow syntax.

## Architecture Diagram

```mermaid
flowchart LR
    A[Private skills repo] -->|sync| B[Canonical store]
    B -->|write tool-specific files| C[Claude / Codex / Kimi / Cursor / Zed / ...]
    B -->|expose list_skills, read_skill| D[MCP server]
    D -->|stdio MCP| C
    E[Workflows/] -->|reference skill names| C
    C -->|resolve at runtime| D
```

The diagram shows the two delivery channels: (1) file-level wiring — instruction files and skills directories created by `sync`, and (2) protocol-level delivery — the MCP server answering `list_skills` and `read_skill`. Tools can use either or both.

## Discovery and Health Checks

The `discover` command scans the filesystem for tool-specific directories (see `AI_TOOL_DIRS` and `SKILL_DIR_NAMES` in `lib/discover.js`) and surfaces anything that is not yet wired. Source: [lib/discover.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/discover.js). The `doctor` command runs a 24-check verification suite and is recommended as a weekly cron job. Source: [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md).

## Common Failure Modes

- **MCP server name collisions.** If another tool on the system registers an MCP server named `omni-skills`, `sync` will overwrite it. The v1.2.2 rename from `skills` to `omni-skills` reduces this risk for the previous name.
- **Stale symlinks.** After moving or renaming the canonical store, symlinks created by older runs can dangle. Re-run `sync` to refresh; the doctor command will flag `⚠` on stale entries.
- **Kimi dual directories.** v1.2.1 and earlier only synced to one of the two Kimi directories. If you are upgrading from a pre-1.2.2 install, run `sync` once to populate both `~/.kimi/skills/` and `~/.kimi-code/skills/`.
- **Tools with no MCP support** (Tabby, PearAI, Void) will only see skills via the file-system wiring. If a skill is meant to be discovered dynamically, prefer a tool with MCP.

## See Also

- Workflow syntax and step types: [examples/workflows/advanced-feature-dev/WORKFLOW.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/workflows/advanced-feature-dev/WORKFLOW.md)
- Configuration schema reference: [config.example.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/config.example.json)
- Version history and breaking changes: [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md)
- Release overview and supported tool list: [RELEASE_NOTES.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/RELEASE_NOTES.md)

---

<a id='page-4'></a>

## Skills Storage, Sync Engine, and Verification

### Related Pages

Related topics: [Omni Skills Overview and Architecture](#page-1), [CLI Commands, Workflows, and Setup](#page-2), [MCP Server and Supported AI Tools](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md)
- [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js)
- [lib/skills.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/skills.js)
- [lib/doctor.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/doctor.js)
- [lib/discover.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/discover.js)
- [lib/setup.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/setup.js)
- [lib/index-gen.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/index-gen.js)
- [lib/fs-utils.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/fs-utils.js)
- [lib/sensitive.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sensitive.js)
- [verify.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/verify.js)
- [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md)
- [examples/example-skill/SKILL.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/example-skill/SKILL.md)
</details>

# Skills Storage, Sync Engine, and Verification

## Overview

Omni Skills is a single-purpose toolkit: it finds every skill and instruction file a developer has accumulated across AI tools, stores them in one canonical location, and wires that location into every AI tool the developer uses. The system has three coordinated layers — **storage**, **sync**, and **verification** — that together prevent drift, duplication, and orphaned configuration. Source: [README.md:1-40]().

The toolkit ships with an 11-command CLI (`sync`, `doctor`, `setup`, `discover`, `classify`, `check`, `report`, `index`, `init`, `mcp`, `help`), an MCP server exposing `list_skills` and `read_skill` to any MCP-aware tool, and a 24-check verification suite. Source: [CHANGELOG.md:1-30]().

## Skills Storage

Omni Skills is intentionally **code only** — the toolkit contains no skills itself. The user's skills live in one or two private repositories that the developer controls. The recommended layout places each skill in a directory with a `SKILL.md` frontmatter file:

```
~/my-skills-private/
  ├── clean-code/SKILL.md
  ├── systematic-debugging/SKILL.md
  ├── refine-requests/SKILL.md
  └── workflows/feature-dev/WORKFLOW.md
```

A minimal skill template is provided so developers can copy and adapt it. Source: [examples/example-skill/SKILL.md:1-10]().

Discovery recognizes a fixed set of skill-directory names and instruction filenames. The supported directory names are `skills`, `.skills`, `ai-skills`, and `agent-skills`. Source: [lib/discover.js:1-20](). The supported instruction file names cover every major tool, including `AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `.clinerules.md`, `.roo-rules`, `CONVENTIONS.md`, `copilot-instructions.md`, and `.github/copilot-instructions.md`. Source: [lib/discover.js:1-15]().

Skills remain **private** because they encode personal coding style, proprietary workflows, and project conventions — intellectual property that has no place in a public toolkit repo. Source: [README.md:120-160]().

## Sync Engine

The sync engine wires the canonical store into every registered AI tool using three portability tiers:

| Tier | Asset Type | Mechanism |
|------|-----------|-----------|
| **A** | `SKILL.md` skills + shared instructions + MCP server | Symlinks + local MCP server exposing `list_skills` / `read_skill` |
| **B** | Hooks | Canonical hooks transpiled into each tool's native hook format |
| **C** | Other assets | Symlinks from the config repo to per-tool paths |

Source: [README.md:60-90]().

The single command `omni-skills sync all` performs tier-A wiring for every supported tool, while `omni-skills sync <tool>` onboards a new tool individually. Source: [README.md:30-50]().

Each tool has a per-tool configuration record describing its instruction file, instruction mode (`symlink`, `opencode-instructions`, etc.), skills directory, MCP config file and format, and hooks config. For example, Codex stores instruction at `~/.codex/AGENTS.md` via symlink and writes MCP to `~/.codex/config.toml` in `codex-toml` format, while Kimi declares a **dual** skills directory array. Source: [lib/setup.js:1-30]():

```javascript
kimi: {
  instructionFile: "~/.kimi/AGENTS.md",
  instructionMode: "symlink",
  skillsDir: ["~/.kimi/skills", "~/.kimi-code/skills"],
  mcp: { file: "~/.kimi/mcp.json", format: "mcpServers" },
  hooks: null
}
```

That dual-array pattern was the fix landed in v1.2.2, where `wireSkillsDir` was extended to accept arrays so skills land in both `~/.kimi/skills/` and `~/.kimi-code/skills/`, with originals backed up to `.skills-bak/`. Source: [CHANGELOG.md:1-10](). The MCP server name was simultaneously renamed from `skills` to `omni-skills` in the same release. Source: [CHANGELOG.md:1-10]().

The MCP server itself is the load-bearing piece for tier A: any tool that supports MCP registers it and calls:

```json
{ "name": "list_skills",  "result": [{ "name": "clean-code", "description": "..." }] }
{ "name": "read_skill",   "arguments": { "name": "systematic-debugging" } }
```

Skills are discovered from the private repos, **live-reloaded** when files change, and exposed as both tools and prompts. Source: [README.md:90-130]().

## Verification & Health Checks

Two complementary systems catch drift before it becomes a problem.

**1. `verify.js` — 24-check suite.** Run after install and before each release, it inspects config loading, skill paths, skills scan (count and duplicates), skill-file validity, `SHARED.md` existence, instruction symlink integrity, per-tool skills directories, and per-tool MCP configs. A healthy run for a 49-skill setup prints:

```
[config]        ✓ loads successfully
[skill paths]   ✓ 2 paths exist
[skills scan]   ✓ 49 skills found, no duplicates
[skill files]   ✓ all files valid
[SHARED.md]     ✓ exists
[instruction]   ✓ 6 symlinks + 1 regular valid
[skills dirs]   ✓ 4 tools, 49 skills each, all healthy
[MCP configs]   ✓ 7 tools, all have skills server
```

Source: [README.md:200-240]().

**2. `omni-skills doctor` — continuous health check.** This command validates symlinks, config, and indexes, while `omni-skills check` scans for orphaned skills and `omni-skills report` produces usage stats. A `cron` job runs `omni-skills doctor` every Sunday at 9:17 AM to catch drift between scheduled syncs. Source: [README.md:240-280](); [CHANGELOG.md:1-30]().

Earlier releases show this verification layer being tightened over time: v1.2.1 made `lib/doctor.js` report ✓ (instead of ⚠) for expected regular files such as Claude and OpenCode instruction files. Source: [CHANGELOG.md:1-15]().

## Common Failure Modes

| Symptom | Likely Cause | Where to Look |
|---------|-------------|---------------|
| Skill missing in a tool | Sync never ran for that tool | Re-run `omni-skills sync all` |
| Duplicate `AGENTS.md` / `GEMINI.md` copies | Tool never pointed at canonical store | `omni-skills check` |
| Orphaned skill after move | Old symlink broken | `omni-skills doctor` |
| Kimi shows old skills only | Pre-v1.2.2 single-directory sync | Re-sync; v1.2.2+ writes to both `~/.kimi/skills` and `~/.kimi-code/skills` |

## See Also

- [Workflows & Step Types](workflows.html) — chainable skill sequences with loops, conditions, and parallel branches
- [MCP Server & Tool Integration](mcp-server.html) — `list_skills` / `read_skill` exposure
- [CLI Command Reference](cli-reference.html) — full syntax for `sync`, `doctor`, `setup`, `discover`, `check`, `report`
- [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md) — release history through v1.2.21

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: moatazhamada/ai-omni-skills-mcp-retrieval

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/moatazhamada/ai-omni-skills

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/moatazhamada/ai-omni-skills

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/moatazhamada/ai-omni-skills

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/moatazhamada/ai-omni-skills

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills

<!-- canonical_name: moatazhamada/ai-omni-skills-mcp-retrieval; human_manual_source: deepwiki_human_wiki -->