# https://github.com/moatazhamada/ai-omni-skills 项目说明书 生成时间：2026-06-22 01:16:02 UTC ## 目录 - [Overview & Getting Started](#page-1) - [System Architecture & Core Modules](#page-2) - [Commands, Workflows & Operations](#page-3) - [Supported Tools & Configuration](#page-4) ## Overview & Getting Started ### 相关页面 相关主题：[System Architecture & Core Modules](#page-2), [Supported Tools & Configuration](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md) - [package.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/package.json) - [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) - [config.example.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/config.example.json) - [examples/example-skill/SKILL.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/example-skill/SKILL.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)
# Overview & Getting Started ## 项目定位与目标 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 全局安装： ```bash 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]()： ```markdown --- name: example-skill description: 'Use when you need a minimal example skill to copy or test the toolkit.' --- ``` ## Workflows：链接多个 Skill Workflows 是把多个 skill 按顺序、条件或并行方式组合起来的 YAML 文件，存放在私有仓库的 `workflows/` 目录下。基础示例是线性的「功能开发」流程 资料来源：[examples/workflows/feature-dev/WORKFLOW.md:1-15]()： ```yaml steps: - refine-requests - speckit-specify - speckit-plan - speckit-implement - speckit-git-commit ``` 高级示例则展示了**循环、条件、并行、重试**等控制流 资料来源：[examples/workflows/advanced-feature-dev/WORKFLOW.md:1-40]()： ```yaml - loop: until: "user says approved" max_iterations: 3 steps: [...] - condition: check: "spec is complex (more than 5 requirements)" then: [...] else: [...] - parallel: branches: [...] ``` 下表总结了工作流支持的步骤类型 资料来源：[README.md:55-60]()： | 类型 | 语法 | 作用 | |------|------|------| | Skill | `skill: name` | 加载并执行单个 skill | | Goal | `goal: "..."` | 步骤的成功条件 | | Retry | `max_retries: 3` | 失败时自动重试 | | Loop | `loop: { until, max_iterations, steps }` | 重复执行直到条件满足 | | Condition | `condition: { check, then, else }` | 按条件分支 | | Parallel | `parallel: { branches: [...] }` | 并行执行多个分支 | ## 架构概览 工具集通过统一的 `config.json` 描述每个 AI 工具的目标位置（指令文件路径、技能目录、MCP 配置、hooks），然后由 `sync`、`doctor`、`setup` 等命令驱动读写操作。MCP 服务器作为可选的统一接口，让支持 MCP 协议的工具（如 Claude Desktop）通过 `list_skills` / `read_skill` 动态读取 skills，避免每次修改都重新生成文件。 ```mermaid flowchart LR A[私有 skills 仓库] -->|sync| B[各 AI 工具目录] B -->|doctor 24 项检查| C[健康报告] A -->|MCP server| D[支持 MCP 的工具] A -->|workflows| E[skill 链式执行] E --> B ``` 资料来源：[CHANGELOG.md:14-22]() 资料来源：[lib/setup.js:1-30]() ## 参与贡献 贡献规范明确：欢迎新增 AI 工具配置、修复 sync/doctor/setup 相关的 bug、补充文档与测试；**不接受**任何 skills 内容、项目特定代码或暴露私有工作上下文的变更 资料来源：[CONTRIBUTING.md:1-30]() ## See Also - Workflows 详解与示例 - 配置参考（26 个 AI 工具的 schema） - MCP 服务器协议说明 --- ## System Architecture & Core Modules ### 相关页面 相关主题：[Commands, Workflows & Operations](#page-3), [Supported Tools & Configuration](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [cli.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/cli.js) - [mcp.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/mcp.js) - [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) - [lib/config.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/config.js) - [lib/skills.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/skills.js) - [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js) - [lib/doctor.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/doctor.js) - [package.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/package.json) - [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md)
# System Architecture & Core Modules 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]()。 ```mermaid flowchart TB User[用户 / AI 工具] --> CLI[cli.js 命令入口] User --> MCP[mcp.js MCP Server] CLI --> Setup[lib/setup.js
初始化与发现] CLI --> Sync[lib/sync.js
同步与软链] CLI --> Doctor[lib/doctor.js
健康检查] CLI --> Skills[lib/skills.js
技能管理] CLI --> Discover[lib/discover.js
扫描工具目录] Setup --> Config[lib/config.js
统一配置] 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（故障排查与健康检查）](#) --- ## Commands, Workflows & Operations ### 相关页面 相关主题：[System Architecture & Core Modules](#page-2), [Supported Tools & Configuration](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [cli.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/cli.js) - [lib/workflows.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/workflows.js) - [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js) - [lib/doctor.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/doctor.js) - [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) - [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)
# Commands, Workflows & Operations ## 一、概述 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 个核心命令，覆盖了从发现、同步到诊断的完整生命周期： | 命令 | 主要职责 | |------|----------| | `sync` | 将 canonical store 中的 skills 与指令文件同步到各 AI 工具的配置目录 | | `doctor` | 健康检查与漂移检测 | | `setup` | 初始化工具配置与扫描已安装的 AI 工具 | | `discover` | 自动发现系统中已存在的 skills 与指令文件 | | `classify` | 对发现的资产进行分类 | | `check` | 运行验证套件 | | `report` | 输出汇总报告 | | `index` | 生成 skill 索引文件 | | `init` | 在新项目中初始化工具包 | | `mcp` | 启动 MCP 服务器 | | `help` | 显示帮助信息 | 资料来源：[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]()： | 类型 | 语法 | 作用 | |------|------|------| | **Skill** | `skill: name` | 加载并执行单个 skill | | **Goal** | `goal: "..."` | 为当前步骤定义成功条件 | | **Retry** | `max_retries: 3` | 失败时自动重试 | | **Loop** | `loop: { until, max_iterations, steps }` | 重复执行直到满足条件 | | **Condition** | `condition: { check, then, else }` | 根据检查结果分支 | | **Parallel** | `parallel: { branches: [...] }` | 并行执行多个分支 | ### 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]()。 ```mermaid 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](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md) - 版本演进记录：[CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md) - 私有仓库结构与配置：[README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md) 中的「How to Store Your Skills」一节 --- ## Supported Tools & Configuration ### 相关页面 相关主题：[Overview & Getting Started](#page-1), [Commands, Workflows & Operations](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [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/discover.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/discover.js) - [lib/sync.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/sync.js) - [lib/hooks.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/hooks.js) - [lib/doctor.js](https://github.com/moatazhamada/ai-omni-skills/blob/main/lib/doctor.js) - [examples/hooks.example.json](https://github.com/moatazhamada/ai-omni-skills/blob/main/examples/hooks.example.json) - [CHANGELOG.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CHANGELOG.md) - [README.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/README.md) - [CONTRIBUTING.md](https://github.com/moatazhamada/ai-omni-skills/blob/main/CONTRIBUTING.md)
# 支持的工具与配置 ## 概述 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` 中以统一结构定义，下表汇总了关键配置字段： | 字段 | 含义 | |------|------| | `instructionFile` | 共享指令文件的目标路径 | | `instructionMode` | 注入方式：`symlink` 或工具原生（如 `opencode-instructions`） | | `skillsDir` | 技能目录；可为字符串或字符串数组 | | `mcp` | MCP 配置（文件 + 格式：`mcpServers` / `codex-toml` / `opencode`） | | `hooks` | Hooks 配置（文件 + 格式：`gemini-json` / `claude-json` / `codex-toml`） | 工具节选示例（来源：`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 命令参考](cli-commands.md) — `sync` / `doctor` / `setup` / `discover` / `mcp` 命令详解 - [MCP 服务器接口](mcp-server.md) — `list_skills` / `read_skill` 规范 - [工作流语法](workflows.md) — `loop` / `condition` / `parallel` 步骤类型 - [私有技能仓库布局](private-skills-repo.md) — 推荐目录结构 --- --- ## Doramagic 踩坑日志 项目：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