OpenSkills 零基础入门指南

0 / 6

概述

OpenSkills 是一款开源的跨编辑器 AI 技能管理工具，旨在解决 Anthropic Skill 格式在不同 AI 编辑器（如 Claude Code、Antigravity、Cursor、Trae 等）中的复用问题。通过提供统一的技能管理接口，OpenSkills 实现了"一次开发/安装，全编辑器复用"的目标。

核心特性

格式兼容：完全保留 Anthropic SKILL.md 标准格式
跨编辑器支持：适配多种 AI 编辑器环境
统一管理：提供标准化的技能安装、同步和读取接口
路径优先级管理：支持项目级、全局级和通用级技能存储

安装要求

系统要求

Node.js ≥ 20.6.0
npm 包管理器

安装命令

# 全局安装 OpenSkills
npm install -g openskills

# 验证安装
openskills --version

# 查看帮助
openskills --help

API 接口

1. 安装命令 (install)

功能描述

从不同来源安装技能到指定路径

命令格式

openskills install <source> [options]

参数说明

参数	类型	必填	描述
source	string	是	技能来源，支持：- GitHub 仓库（如 `anthropics/skills/pdf`）- 本地路径（如 `./my-skill`）- Git URL
--project	flag	否	安装到项目级目录（默认）
--global	flag	否	安装到全局目录
--universal	flag	否	安装到跨编辑器通用目录

安装路径映射表

安装模式	Windows 路径示例	macOS/Linux 路径示例	适用场景
--project（默认）	`当前项目/.claude/skills`	`当前项目/.claude/skills`	Claude Code 项目级技能
--global	`C:\Users\<用户>\.claude\skills`	`~/.claude/skills`	Claude Code 全局技能
--universal	`当前项目/.agent/skills`	`当前项目/.agent/skills`	跨编辑器通用技能

使用示例

# 安装官方 PDF 技能（项目级）
openskills install anthropics/skills/pdf

# 安装 Excel 技能（全局级）
openskills install anthropics/skills/xlsx --global

# 安装前端设计技能（通用级）
openskills install anthropics/skills/frontend-design --universal

# 安装本地自定义技能
openskills install ./my-custom-skill --project

# 批量安装所有官方技能
openskills install anthropics/skills --project

2. 同步命令 (sync)

功能描述

扫描已安装的技能并生成/更新 AGENTS.md 文件

命令格式

openskills sync

扫描路径优先级

当前项目/.agent/skills（--universal 安装）
用户目录/.agent/skills（全局通用技能）
当前项目/.claude/skills（--project 安装）
用户目录/.claude/skills（--global 安装）

输出文件

AGENTS.md：包含所有已安装技能的标准化 XML 描述
位置：当前工作目录

文件格式示例

<agent_capabilities>
  <skill>
    <name>pdf</name>
    <description>处理 PDF 文件的技能</description>
    <path>./.agent/skills/pdf</path>
  </skill>
  <!-- 更多技能... -->
</agent_capabilities>

3. 读取命令 (read)

功能描述

读取指定技能的完整内容

命令格式

openskills read <skill-name>

参数说明

参数	类型	必填	描述
skill-name	string	是	技能名称（区分大小写）

读取规则

按 sync 命令的路径优先级扫描
找到第一个匹配的技能后停止
输出技能完整内容（YAML 元信息 + 操作指令）

使用示例

# 读取 PDF 技能内容
openskills read pdf

# 读取 Excel 技能内容
openskills read xlsx

4. 列表命令 (list)

功能描述

列出所有已安装的技能

命令格式

openskills list

输出格式

已安装的技能列表：
- pdf (PDF 处理)
- xlsx (Excel 处理)
- frontend-design (前端设计)

错误处理

常见错误码

错误码	描述	解决方案
ERR_SKILL_NOT_FOUND	技能未找到	1. 使用 `openskills list` 确认技能名称2. 检查技能是否已安装3. 确认技能名称大小写
ERR_INSTALL_FAILED	安装失败	1. 检查网络连接2. 确认技能源地址正确3. 检查磁盘空间和权限
ERR_PATH_RESOLUTION	路径解析失败	1. 检查路径格式2. 使用手动安装方案（见下文）
ERR_SYNC_FAILED	同步失败	1. 检查文件写入权限2. 确认技能目录存在

Windows 特殊处理方案

当 openskills install --universal 在 Windows 上出现路径解析问题时，可使用手动方案：

# 1. 克隆技能仓库
git clone https://github.com/anthropics/skills.git temp-skills

# 2. 创建目标目录
mkdir -p C:\Users\<用户名>\Desktop\<项目名>\.agent\skills

# 3. 复制文件
xcopy temp-skills\* C:\Users\<用户名>\Desktop\<项目名>\.agent\skills /E /I /Y

# 4. 清理临时文件
rmdir /s /q temp-skills

编辑器适配指南

Claude Code

安装技能到 .claude/skills 目录
Claude Code 会自动识别并加载

Antigravity / Cursor / Trae

安装技能到 .agent/skills 目录（使用 --universal 参数）
执行 openskills sync 生成 AGENTS.md
将 AGENTS.md 内容导入编辑器的：
- 系统提示词配置
- Rule（规则）配置
- Workflow（工作流）配置

通用适配流程

# 1. 安装技能（通用目录）
openskills install anthropics/skills/pdf --universal

# 2. 同步技能信息
openskills sync

# 3. 查看生成的 AGENTS.md
cat AGENTS.md

# 4. 将 AGENTS.md 内容复制到编辑器配置中

最佳实践

1. 技能管理策略

项目专用技能：使用 --project 安装到项目目录
常用工具技能：使用 --global 安装到全局目录
跨编辑器技能：使用 --universal 安装到通用目录

2. 版本控制

将 .claude/skills 或 .agent/skills 目录加入 .gitignore
在项目文档中记录所需的技能列表
使用 openskills list 生成技能清单

3. 团队协作

# 创建技能配置文件 skills.json
{
  "required": [
    "anthropics/skills/pdf",
    "anthropics/skills/xlsx",
    "anthropics/skills/frontend-design"
  ],
  "optional": [
    "anthropics/skills/image-processing"
  ]
}

# 安装脚本 install-skills.sh
#!/bin/bash
openskills install anthropics/skills/pdf --universal
openskills install anthropics/skills/xlsx --universal
openskills install anthropics/skills/frontend-design --universal
openskills sync

4. 自定义技能开发

创建符合 Anthropic Skill 格式的 SKILL.md 文件

使用本地路径安装：

openskills install ./my-skill --universal

测试技能读取：
```
openskills read my-skill
```

故障排除

Q1: 技能安装后编辑器无法识别

解决方案：

确认安装路径正确
执行 openskills sync 更新 AGENTS.md
重启编辑器
检查编辑器是否支持 AGENTS.md 格式

Q2: 同名技能冲突

解决方案：

查看技能优先级：项目级 > 全局级
使用 openskills list 查看所有安装位置
移除低优先级版本或重命名技能

Q3: 技能内容读取失败

解决方案：

确认技能名称正确（区分大小写）
检查技能文件完整性

重新安装技能：

openskills uninstall <skill-name>
openskills install <skill-source>