Related Pages

Related topics: CLI Commands, Workflows, and Setup, MCP Server and Supported AI Tools, Skills Storage, Sync Engine, and Verification

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:

Source: README.md:80-95

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:

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 — version history and feature additions
• CONTRIBUTING.md — contribution guidelines and what is accepted
• RELEASE_NOTES.md — release notes for v1.0.0 and later
• GitHub Discussions — community Q&A and feature ideas
• GitHub Issues — bug reports and feature requests

Related Pages

Related topics: Omni Skills Overview and Architecture, Skills Storage, Sync Engine, and Verification

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.

Related Pages

Related topics: Omni Skills Overview and Architecture, Skills Storage, Sync Engine, and Verification

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.

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 inspects mcp.format and dispatches to one of several writers.

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.

A truncated view of how codex-toml output looks:

# >>> 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. Each entry in config.example.json defines four fields: instructionFile, instructionMode, skillsDir, mcp, and hooks. Source: config.example.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.
• 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.

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 and 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

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. The doctor command runs a 24-check verification suite and is recommended as a weekly cron job. Source: 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
• Configuration schema reference: config.example.json
• Version history and breaking changes: CHANGELOG.md
• Release overview and supported tool list: RELEASE_NOTES.md

Related Pages

Related topics: Omni Skills Overview and Architecture, CLI Commands, Workflows, and Setup, MCP Server and Supported AI Tools

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:

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:

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:

{ "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

See Also

• Workflows & Step Types — chainable skill sequences with loops, conditions, and parallel branches
• MCP Server & Tool Integration — list_skills / read_skill exposure
• CLI Command Reference — full syntax for sync, doctor, setup, discover, check, report
• CHANGELOG.md — release history through v1.2.21

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/moatazhamada/ai-omni-skills

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/moatazhamada/ai-omni-skills

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/moatazhamada/ai-omni-skills

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using ai-omni-skills-mcp-retrieval with real data or production workflows.

• Configuration risk requires verification - GitHub / issue