Loading... # OpenSkills 通用技能加载器技术分析 # 一、概述 ## 1. 简介 ### A. 是什么 OpenSkills 是一个通用技能加载器，旨在将 Anthropic 的技能系统带给所有 AI 编码代理。它是一个 CLI 工具，能够让 Claude Code、Cursor、Windsurf、Aider、Codex 以及任何能够读取 AGENTS.md 文件的代理使用相同的技能格式。 ### B. 为什么重要 - 统一了不同 AI 编码代理的技能生态系统 - 提供了与 Claude Code 完全兼容的技能格式 - 支持按需加载技能，保持上下文清洁 - 允许技能存储在项目仓库中，便于版本控制 ### C. 核心价值 OpenSkills 可以被视为 SKILL.md 的通用安装程序，实现了"一次编写，到处运行"的技能分发理念。 ## 2. 技术背景 ### A. Anthropic 技能系统 Claude Code 将技能作为 SKILL.md 文件分发，并在系统提示词中通过 available_skills XML 块暴露这些技能。当用户请求特定任务时，Claude 会动态加载匹配的技能。 ### B. 兼容性设计 OpenSkills 生成与 Claude Code 完全相同的 available_skills XML 格式，写入 AGENTS.md 文件，使任何能够读取该文件的代理都能使用 Claude Code 技能。 # 二、工作原理 ## 1. 系统架构 ```mermaid graph TB User[用户] --> CLI[OpenSkills CLI] CLI --> Install[install 命令] CLI --> Sync[sync 命令] CLI --> Read[read 命令] Install --> Source[技能来源] Source --> GitHub[GitHub 仓库] Source --> Local[本地路径] Source --> Private[私有 Git 仓库] Install --> SkillsDir[.claude/skills 或 .agent/skills] SkillsDir --> AGENTS[AGENTS.md] Sync --> AGENTS Read --> Agent[AI 编码代理] Agent --> Claude[Claude Code] Agent --> Cursor[Cursor] Agent --> Windsurf[Windsurf] Agent --> Aider[Aider] ```  ## 2. 技能加载机制 ### A. Claude Code 原生方式 Claude Code 通过内置的 Skill 工具调用技能，技能存储在 .claude/skills 目录中，由系统提示词自动管理。 ### B. OpenSkills 方式 OpenSkills 通过 CLI 命令 npx openskills read <skill-name> 加载技能内容，代理读取 AGENTS.md 文件获取技能列表。 ### C. 两者对比 | 方面 | Claude Code | OpenSkills | |------|-------------|------------| | 提示格式 | available_skills XML | 相同的 XML | | 技能存储 | .claude/skills/ | .claude/skills/（默认） | | 调用方式 | Skill("name") 工具 | npx openskills read <name> | | 技能市场 | Anthropic 市场 | GitHub（anthropics/skills） | | 渐进式加载 | 支持 | 支持 | # 三、核心功能 ## 1. 安装技能 ### A. 从 Anthropic 市场安装 ```bash npx openskills install anthropics/skills ``` ### B. 从任意 GitHub 仓库安装 ```bash npx openskills install your-org/your-skills ``` ### C. 从本地路径安装 ```bash npx openskills install ./local-skills/my-skill ``` ### D. 从私有 Git 仓库安装 ```bash npx openskills install git@github.com:your-org/private-skills.git ``` ## 2. 同步技能 ```bash npx openskills sync ``` 该命令会更新 AGENTS.md 文件（或自定义输出文件），将所有已安装的技能以 available_skills XML 格式写入。 ## 3. 读取技能 ```bash npx openskills read <skill-name> ``` 代理通过此命令获取特定技能的完整内容。 ## 4. 管理技能 ### A. 列出已安装技能 ```bash npx openskills list ``` ### B. 更新技能 ```bash npx openskills update [name...] ``` ### C. 移除技能 ```bash npx openskills remove <name> ``` ### D. 交互式管理 ```bash npx openskills manage ``` # 四、通用模式 ## 1. 多代理环境 当同时使用 Claude Code 和其他代理时，使用 --universal 标志将技能安装到 .agent/skills 目录，避免与 Claude 的插件市场冲突。 ```bash npx openskills install anthropics/skills --universal ``` ## 2. 技能优先级 优先级顺序（从高到低）： 1. ./.agent/skills/ 2. ~/.agent/skills/ 3. ./.claude/skills/ 4. ~/.claude/skills/ # 五、SKILL.md 格式 ## 1. 基本结构 ```yaml --- name: pdf description: Comprehensive PDF manipulation toolkit for extracting text and tables... --- ``` ## 2. 完整示例 ```markdown --- name: pdf description: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. --- # PDF Skill Instructions When the user asks you to work with PDFs, follow these steps: 1. Install dependencies: `pip install pypdf2` 2. Extract text using scripts/extract_text.py 3. Use references/api-docs.md for details ``` ## 3. 技能特点 - 按需加载：仅在需要时加载技能，保持代理上下文清洁 - 自包含：技能包含所有必要的指令和资源 - 可版本控制：技能可以作为项目的一部分进行版本管理 # 六、创建自定义技能 ## 1. 最小结构 ``` my-skill/ └── SKILL.md ``` ## 2. 完整结构 ``` my-skill/ ├── SKILL.md ├── references/ ├── scripts/ └── assets/ ``` ## 3. 安装自定义技能 ```bash npx openskills install ./my-skill ``` ## 4. 本地开发与符号链接 ```bash git clone git@github.com:your-org/my-skills.git ~/dev/my-skills mkdir -p .claude/skills ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill ``` ## 5. 技能创作指南 使用 skill-creator 技能获取创作指导： ```bash npx openskills install anthropics/skills npx openskills read skill-creator ``` # 七、技术实现 ## 1. 命令行标志 | 标志 | 说明 | |------|------| | --global | 全局安装到 ~/.claude/skills（默认为项目安装） | | --universal | 安装到 .agent/skills/ 而非 .claude/skills/ | | -y, --yes | 跳过提示（适用于 CI） | | -o, --output <path> | sync 的输出文件（默认：AGENTS.md） | ## 2. AGENTS.md 生成 OpenSkills 自动生成符合 Anthropic 规范的 AGENTS.md 文件，包含完整的 available_skills XML 块，供代理读取和使用。 # 八、设计理念 ## 1. 为什么选择 CLI 而非 MCP ### A. MCP 的定位 MCP（Model Context Protocol）用于动态工具，需要运行服务器。 ### B. 技能的特点 - 技能是静态文件，无需服务器 - 适用于每个代理，无需 MCP 支持 - 符合 Anthropic 的设计理念，SKILL.md 即规范 ### C. 结论 MCP 和技能解决不同问题。OpenSkills 保持技能的轻量级和通用性。 ## 2. 渐进式披露 技能仅在需要时加载，避免污染代理的上下文窗口，提高响应效率。 ## 3. 仓库友好 技能存储在项目目录中，可以随项目一起版本控制和共享。 ## 4. 私有友好 支持从本地路径或私有 Git 仓库安装技能，适用于企业环境。 # 九、使用场景 ## 1. 多代理开发 开发者使用不同的 AI 编码代理（Claude Code、Cursor、Windsurf 等），希望共享同一套技能库。 ## 2. 团队协作 团队创建自定义技能，通过私有 Git 仓库共享，确保所有成员使用相同的技能集。 ## 3. CI/CD 集成 使用 --yes 标志在自动化流程中安装和同步技能。 # 十、系统要求 ## 1. 运行环境 - Node.js 20.6+ - Git（用于克隆仓库） ## 2. 安装方式 ```bash npm install -g openskills ``` 或使用 npx 直接运行： ```bash npx openskills install anthropics/skills ``` # 十一、项目状态 ## 1. 开源信息 - 许可证：Apache 2.0 - GitHub：numman-ali/openskills - Stars：7.5k+ - Forks：510+ - 最新版本：v1.5.0（2026 年 1 月 17 日） ## 2. 技术栈 - TypeScript 96.9% - JavaScript 3.1% # 十二、常见问题 ## 1. 与 Claude Code 的关系 OpenSkills 实现了 Anthropic 的 Agent Skills 规范，但并非 Anthropic 官方项目。Claude、Claude Code 和 Agent Skills 是 Anthropic PBC 的商标。 ## 2. 多次读取优化 对于多次读取，建议使用逗号分隔的名称： ```bash npx openskills read foo,bar ``` ## 3. 技能更新跟踪 如果技能在更新跟踪之前安装，需要重新安装一次以记录其来源。 *** ## 参考资料 1. [OpenSkills GitHub Repository](https://github.com/numman-ali/openskills) 2. [Anthropic Agent Skills Specification](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) 3. [npm Package](https://www.npmjs.com/package/openskills) 最后修改：2026 年 01 月 31 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏