项目定位与目标

Omni Skills 是一个通用基础设施型 CLI 工具集（不是 skills 内容本身），它解决的问题是：当用户在多个 AI 编程助手（Claude、Codex、Kimi、Cursor、Kilocode、OpenCode、Cline、Roo Code、Windsurf 等）之间切换时，各工具的指令文件（AGENTS.md、GEMINI.md、rules.md）与 skills 目录分散在各处，容易出现重复、漂移和孤立的副本。

项目明确将自身定位为「代码层面」的工具集，用户的 skills 内容始终保存在私有仓库中，工具集只负责把这些内容同步、对齐、检测到各个 AI 工具的目标位置。这种「工具集公开、内容私有」的边界被反复强调。

资料来源：README.md:1-30 资料来源：slack-message.txt:1-12

核心能力一览

CLI 提供 11 个命令，覆盖从扫描、分类、同步到健康检查的完整生命周期 资料来源：CHANGELOG.md:13-22：

• sync — 将规范仓库中的 skills 同步到各 AI 工具目录
• doctor — 执行 24 项验证检查，确认工具集成健康状态
• setup — 自动扫描已安装的 AI 工具，建议清理方案
• discover — 查找分散的指令文件与 skills 目录
• classify — 对发现的文件进行分类（保留/归档/删除）
• check / report — 验证与生成报告
• index — 生成 skill 索引
• init — 初始化项目配置
• mcp — 启动 MCP 服务器，对外暴露 list_skills 与 read_skill
• help — 帮助信息

工具集支持 26 个 AI 工具的配置，每种工具的指令文件、技能目录、MCP 配置和 hooks 都可以在 config.example.json 中按统一 schema 定义 资料来源：config.example.json:1-30。

快速上手

安装

通过 npm 全局安装：

npm install -g ai-omni-skills

发布采用 npm provenance 机制，可以在 npm 页面验证包的来源 资料来源：CHANGELOG.md:5-8。

第一次运行

安装后推荐按以下顺序操作 资料来源：CHANGELOG.md:14-22：

1. 运行 omni-skills setup，自动检测已安装的 AI 工具与分散的 skills 目录
2. 运行 omni-skills discover，扫描所有候选指令文件
3. 运行 omni-skills classify，对扫描结果分类
4. 运行 omni-skills doctor，查看 24 项健康检查结果

每周日上午 9:17 可配置自动 cron 执行 omni-skills doctor，防止配置漂移 资料来源：README.md:105-110。

推荐的私有仓库结构

工具集本身是公开的代码，但用户的 skills 与 workflows 应放在私有仓库中 资料来源：README.md:62-90：

~/my-skills-private/
  ├── SHARED.md                # 生成的共享指令
  ├── INDEX.md                 # 生成的 skill 索引
  ├── config.json              # 工具集配置
  ├── clean-code/SKILL.md
  ├── systematic-debugging/SKILL.md
  ├── refine-requests/SKILL.md
  ├── ...
  ├── projects/                # 每个项目的指令文件
  ├── workflows/               # 可链接的 skill 序列
  └── large-projects/          # 大型项目的辅助脚本

每个 skill 是一个包含 SKILL.md 的目录，前置元数据描述使用场景 资料来源：examples/example-skill/SKILL.md:1-5：

Omni Skills 是一个 CLI 工具包（当前版本 v1.2.21），其核心定位是“通用基础设施”，负责将分散在多个 AI 编程工具（Claude、Codex、Kimi、Cursor、Gemini 等共 26 种）中的 skills、instruction 文件、hooks、MCP 配置统一到一个规范化的私有仓库中。它本身不包含任何业务级 skill，所有 skill 由用户维护在私有仓库里 资料来源：README.md:1-120。

总体架构概览

整个项目采用 CLI + 库模块 + MCP Server 三层结构。cli.js 是命令入口，解析用户输入并分发到 lib/ 下的各个模块；mcp.js 暴露一个 MCP（Model Context Protocol）服务器，让任意支持 MCP 的 AI 工具都可以远程读取 skill 内容；lib/ 目录下的纯函数模块负责具体能力实现。这种分层保证了各子模块可独立测试、可按需组合 资料来源：cli.js:1-50, 资料来源：mcp.js:1-40。

flowchart TB
    User[用户 / AI 工具] --> CLI[cli.js 命令入口]
    User --> MCP[mcp.js MCP Server]
    CLI --> Setup[lib/setup.js<br/>初始化与发现]
    CLI --> Sync[lib/sync.js<br/>同步与软链]
    CLI --> Doctor[lib/doctor.js<br/>健康检查]
    CLI --> Skills[lib/skills.js<br/>技能管理]
    CLI --> Discover[lib/discover.js<br/>扫描工具目录]
    Setup --> Config[lib/config.js<br/>统一配置]
    Sync --> Config
    Doctor --> Config
    Skills --> Private[用户私有 skills 仓库]
    Sync --> Tools[26 种 AI 工具配置目录]

CLI 命令层（Command Layer）

cli.js 是整个工具的"门面"，对外暴露 11 条命令：sync、doctor、setup、discover、classify、check、report、index、init、mcp、help 资料来源：CHANGELOG.md:1-30。每条命令对应一个 lib/ 子模块，它们共享 lib/config.js 提供的统一配置对象，从而避免重复解析 ~/.config/skills/config.json。这种"命令即模块"的模式让新增 AI 工具时只需扩展 config.js 而不必改动命令分发逻辑。

核心能力模块（Core Capability Modules）

配置与发现

lib/config.js 定义了所有支持的 AI 工具描述符（tool descriptor），包括每个工具的 instructionFile、instructionMode、skillsDir、mcp 与 hooks 字段 资料来源：lib/setup.js:1-60。例如 claude 工具使用 symlink 模式指向 ~/.claude/CLAUDE.md，而 opencode 使用 opencode-instructions 自定义模式写入 opencode.jsonc。

lib/discover.js 负责扫描用户文件系统，它通过 AI_TOOL_DIRS 常量遍历已知工具目录，并递归查找常见的 instruction 文件名（如 AGENTS.md、GEMINI.md、.cursorrules、copilot-instructions.md 等）资料来源：lib/discover.js:1-50。扫描深度限制为 4 层（maxDepth = 4），并跳过 node_modules、.git、build、dist 等噪声目录。

同步与软链（Sync & Symlink）

lib/sync.js 是最复杂的模块，负责把规范化仓库中的 skill 与 instruction 文件以软链接形式分发到各 AI 工具的本地配置目录。其核心函数 wireSkillsDir 支持数组形式的目录列表（例如 Kimi 同时有 ~/.kimi/skills 与 ~/.kimi-code/skills 两条路径）资料来源：CHANGELOG.md:1-30。原有的 native skill 在覆盖前会被备份到 .skills-bak/`，从而避免破坏用户的本地资产。

健康检查（Doctor）

lib/doctor.js 实现了一套 24 项验证检查（verify.js），覆盖配置完整性、软链有效性、MCP 配置语法等 资料来源：CHANGELOG.md:1-30。README 提到 omni-skills doctor` 可设为每周日凌晨 9:17 自动运行，确保分散在多工具的 skill 不会"漂移" 资料来源：README.md:1-200。

MCP 接入

mcp.js 提供 list_skills 与 read_skill 两个 MCP 工具，使任意兼容 MCP 的 AI 客户端（Claude Desktop、Cline、Zed 等）都能即时读取用户私有仓库中的 skill 资料来源：CHANGELOG.md:1-30。在 v1.2.2 中，mcpServerName 从 skills 重命名为 omni-skills，以避免与通用命名冲突。

私有仓库与公共工具箱的边界

项目明确区分了工具箱（公开仓库）与 skills（私有仓库）的职责边界。package.json 将自身声明为纯 CLI 元信息包，private 段说明 skills 永远不应进入此仓库 资料来源：package.json:1-50。推荐结构为：

~/my-skills-private/
  ├── SKILL.md / *.md      ← 规范化的指令文件
  ├── workflows/           ← 个人工作流定义（如 feature-dev/）
  └── large-projects/      ← 各大型项目的 ensure_symlinks.sh

工作流（Workflow）以 WORKFLOW.md 文件形式存在，支持 6 种步骤类型：skill、goal、retry、loop、condition、parallel，通过 YAML frontmatter 声明 资料来源：examples/workflows/advanced-feature-dev/WORKFLOW.md:1-80。例如 advanced-feature-dev 工作流就同时使用了 loop（反复打磨 spec 直到用户说 approved）、condition（根据需求数量决定 plan vs tasks）、parallel（并行运行 lint、test、analyze）。

总结

Omni Skills 的核心模块采用职责单一与配置驱动的设计：cli.js 负责命令分发，lib/*.js 负责具体能力，mcp.js 负责跨工具接入，lib/config.js 是唯一的"事实来源"。这种架构使得新增 AI 工具时只需扩展配置表，而无需触碰命令或同步逻辑——这也是它能在 26 种工具间保持一致的根因。

See Also

• Configuration Reference（配置参考）
• Workflow DSL Specification（工作流 DSL 规范）
• Troubleshooting & Health Checks（故障排查与健康检查）

一、概述

Omni Skills 是一个用于统一管理多个 AI 编码工具（如 Claude、Codex、Kimi、Cursor 等）的命令行工具包。其核心设计理念是「code only」：工具包本身只提供基础设施，而用户的技能（skills）、指令文件（instruction files）和工作流（workflows）则保存在用户自己的私有仓库中 资料来源：README.md。

工具包通过 CLI 命令与工作流引擎两部分协同工作，将分散在各 AI 工具中的 skills 统一收集到一个canonical store中，再通过符号链接（symlinks）、MCP 服务器以及 hooks 转译机制分发到各工具的配置目录，从而实现「一处定义、多端可用」的目标 资料来源：README.md。

最新发布的 v1.2.21 版本在 npm 上以 provenance 方式发布，确保了供应链的可验证性 资料来源：CHANGELOG.md。

二、CLI 命令体系

omni-skills CLI 提供 11 个核心命令，覆盖了从发现、同步到诊断的完整生命周期：

资料来源：README.md、CHANGELOG.md。

其中 sync 命令是最常用的入口，例如 omni-skills sync all 会一次性将所有支持的工具（Claude、Codex、Kimi、Gemini、Cursor、Cline、Zed 等）进行同步 资料来源：README.md。

三、工作流引擎（Workflows）

工作流是 Omni Skills 的核心创新之一，它允许用户将多个 skill 串联成可复用的执行序列。工作流定义文件存放在用户的私有仓库下 workflows/ 目录中（如 workflows/release-prep/WORKFLOW.md），每个工作流以 YAML frontmatter + Markdown 描述的形式存在 资料来源：examples/workflows/release-prep/WORKFLOW.md、examples/workflows/feature-dev/WORKFLOW.md。

1. 步骤类型

工作流引擎支持 6 种步骤类型 资料来源：README.md、examples/workflows/advanced-feature-dev/WORKFLOW.md：

2. 内置示例工作流

仓库自带四个示例工作流，分别对应典型开发场景：

• release-prep：发布前的 lint、test、commit 三步检查 资料来源：examples/workflows/release-prep/WORKFLOW.md。
• feature-dev：从需求澄清到代码提交的完整功能开发链 资料来源：examples/workflows/feature-dev/WORKFLOW.md。
• advanced-feature-dev：综合运用 loop、condition、parallel 的高级特性 资料来源：examples/workflows/advanced-feature-dev/WORKFLOW.md。
• debug-trace：结构化的 bug 定位与修复流程 资料来源：examples/workflows/debug-trace/WORKFLOW.md。

graph TD
    A[refine-requests] --> B{loop: 规格审批}
    B -->|未通过| B
    B -->|approved| C{condition: 是否复杂}
    C -->|>5 需求| D[speckit-plan]
    C -->|<=5 需求| E[speckit-tasks]
    D --> F[speckit-implement]
    E --> F
    F --> G[parallel: 质量检查]
    G --> G1[lint-and-validate]
    G --> G2[testing-patterns]
    G --> G3[speckit-analyze]
    G1 --> H[speckit-git-commit]
    G2 --> H
    G3 --> H

四、核心运维操作

1. 同步（Sync）

sync 命令通过 wireSkillsDir 函数将 skills 目录挂载到各 AI 工具的原生目录。Kimi CLI 由于历史原因同时存在 ~/.kimi/skills/ 和 ~/.kimi-code/skills/ 两个目录，sync 会同时同步两者并把原始目录备份到 .skills-bak/ 资料来源：lib/setup.js、CHANGELOG.md。

2. 健康检查（Doctor）

doctor 命令会执行 24 项验证检查（verify.js），并对 expected regular files（如 Claude、OpenCode 的配置）正确显示 ✓ 而非 ⚠ 资料来源：CHANGELOG.md。README 中提到，作者本人配置了每周日上午 9:17 自动运行 omni-skills doctor 的 cron 任务，确保配置长期不漂移 资料来源：README.md。

3. 自动发现（Discover）

discover.js 扫描系统中已知的 skills 目录（skills、.skills、ai-skills、agent-skills）和指令文件名（如 AGENTS.md、.cursor/rules、CONVENTIONS.md 等），并跳过 node_modules、.git、build、dist 等干扰目录 资料来源：lib/discover.js。这使得从旧的散乱配置迁移到 canonical store 变得简单。

4. MCP 服务器

工具包内置一个本地 MCP 服务器，统一暴露 list_skills 与 read_skill 两个工具，任何支持 MCP 的 AI 工具都可以注册并调用它们，技能文件会被 live-reload 资料来源：README.md。在 v1.2.2 版本中，服务器名称从 skills 重命名为 omni-skills 以避免冲突 资料来源：CHANGELOG.md。

五、常见失败模式与排错

1. 同步后部分工具未生效：通常是配置文件中 skillsDir 或 mcp.file 路径错误，可通过 omni-skills doctor 快速定位。
2. Kimi 同步重复：旧版本只同步单个目录，v1.2.2 已修复为数组形式同时处理两个目录 资料来源：CHANGELOG.md。
3. MCP 工具名称冲突：升级后若旧名称 skills 仍被引用，需手动清理客户端缓存 资料来源：CHANGELOG.md。
4. 指令文件重复：作者在迁移过程中清理了 77 份重复的 AGENTS.md/GEMINI.md，建议运行 omni-skills discover + classify 后再 sync 资料来源：README.md。

See Also

• 入门与安装：README.md
• 版本演进记录：CHANGELOG.md
• 私有仓库结构与配置：README.md 中的「How to Store Your Skills」一节

支持的工具与配置

概述

Omni Skills 是一个 CLI 工具包，用于统一散落在多个 AI 编码工具中的技能（SKILL.md）和指令文件（AGENTS.md / CLAUDE.md 等）。其核心是维护单一规范存储（canonical store），并将其同步到所有已安装的 AI 工具中。

"It finds all the skills and instruction files you've accumulated, puts them in one place, and wires them into every AI tool you use."

资料来源：README.md

本页聚焦该工具包支持的 AI 工具清单、配置结构以及发现/同步机制。

支持的 AI 工具

Omni Skills 当前配置支持 26 种 AI 工具。资料来源：CHANGELOG.md:1.0.0 每个工具在 lib/setup.js 中以统一结构定义，下表汇总了关键配置字段：

工具节选示例（来源：lib/setup.js）：claude 使用 symlink 模式注入 ~/.claude/CLAUDE.md，MCP 通过 ~/.claude/mcp.json 注册；kimi 的 skillsDir 为数组 ["~/.kimi/skills", "~/.kimi-code/skills"]，以同步到双目录；opencode 使用 opencode-instructions 原生模式而非 symlink。资料来源：lib/setup.js

完整列表：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、Z.AI (GLM 5.2)。资料来源：CHANGELOG.md:1.0.0

注意：Z.AI (GLM 5.2) 不直接接入，而是"通过现有工具工作"——例如在 Claude Code、Cline 或 Zed 中配置 GLM Coding Plan 密钥。资料来源：CHANGELOG.md:Notes

发现机制

lib/discover.js 实现了自动扫描逻辑，用于 doctor / setup / sync 命令的前置探测：

• 技能目录白名单：['skills', '.skills', 'ai-skills', 'agent-skills']。资料来源：lib/discover.js
• 指令文件白名单：包括 AGENTS.md、CLAUDE.md、GEMINI.md、.cursorrules、.clinerules.md、.roo-rules、.roorules、CONVENTIONS.md、copilot-instructions.md 等。资料来源：lib/discover.js
• 扫描深度：默认 maxDepth = 4，跳过 node_modules、.git、build、dist、.next、coverage 等噪声目录。资料来源：lib/discover.js

同步与可移植性

三层可移植性模型

根据 README.md，资产分为三个层级：资料来源：README.md

• 层级 A：SKILL.md 技能 + 共享指令 + MCP 服务器——通过 symlinks 实现；
• 层级 B：Hooks——规范 hooks 转译为各工具原生格式（如 claude-json、gemini-json），由 lib/hooks.js 处理；
• 层级 C：其他资产——从配置仓库到工具特定路径的 symlinks。

MCP 服务器

每个支持 MCP 的工具可注册 omni-skills 服务器（注：v1.2.2 起从 skills 重命名），调用 list_skills 与 read_skill 工具。资料来源：CHANGELOG.md:1.2.2

关键修复

• v1.2.2：lib/sync.js 的 wireSkillsDir 现在接受目录数组，修复 Kimi CLI 双技能目录同步问题；原始原生技能备份至 .skills-bak/。资料来源：CHANGELOG.md:1.2.2
• v1.2.1：lib/doctor.js 修正误报——期望的常规文件（Claude、OpenCode）现显示 ✓ 而非 ⚠。资料来源：CHANGELOG.md:1.2.1
• v1.2.4–1.2.5：增加 npm 徽章与 provenance 标记。资料来源：CHANGELOG.md:1.2.4

验证与扩展

• node verify.js 执行 24 项验证检查；npm test 运行 14 个单元测试。资料来源：CHANGELOG.md:1.0.0
• 新增工具配置应参考 config.example.json 中的模式；项目不接受技能或指令文件本身（属于用户私有仓库）。资料来源：CONTRIBUTING.md

常见限制

• 仓库仅含工具包代码；技能文件与工作流存放于用户的私有 workflows/ 目录。资料来源：README.md
• Z.AI (GLM 5.2) 间接接入，需借助已支持的工具。
• v1.2.2 之前会遗漏 Kimi 的 ~/.kimi-code/skills/ 同步。

另请参阅

• CLI 命令参考 — sync / doctor / setup / discover / mcp 命令详解
• MCP 服务器接口 — list_skills / read_skill 规范
• 工作流语法 — loop / condition / parallel 步骤类型
• 私有技能仓库布局 — 推荐目录结构

Pitfall Log / 踩坑日志

项目：moatazhamada/ai-omni-skills-mcp-retrieval

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/moatazhamada/ai-omni-skills | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/moatazhamada/ai-omni-skills | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/moatazhamada/ai-omni-skills | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/moatazhamada/ai-omni-skills | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/moatazhamada/ai-omni-skills | release_recency=unknown