# https://github.com/numman-ali/openskills 项目说明书
生成时间：2026-05-16 16:02:37 UTC
## 目录
- [项目概述](#page-overview)
- [快速开始](#page-quick-start)
- [系统架构](#page-architecture)
- [CLI命令参考](#page-cli-commands)
- [install命令详解](#page-install-command)
- [sync命令详解](#page-sync-command)
- [update命令详解](#page-update-command)
- [SKILL.md格式规范](#page-skill-md-format)
- [数据存储与管理](#page-data-storage)
- [贡献指南](#page-contributing)
## 项目概述
### 相关页面
相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)
- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)
- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)
- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)
- [CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/numman-ali/openskills/blob/main/CONTRIBUTING.md)
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)
# 项目概述
OpenSkills 是一个开源的 Node.js CLI 工具，旨在为 AI 编码代理提供标准化的技能（Skills）管理和分发机制。该项目完全兼容 Anthropic 的 SKILL.md 格式规范，使技能可以在不同的 AI 代理平台之间无缝移植和使用。
## 项目定位与核心价值
OpenSkills 的核心定位是**通用技能加载器**。在 AI 代理的工作场景中，技能是静态的指令和资源的集合，与 MCP（Model Context Protocol）的动态工具调用形成互补。项目采用 SKILL.md 文件作为技能的唯一载体，无需运行服务器，使得技能具备天然的跨平台兼容性。
**核心价值主张：**
- **Exact Claude Code 兼容性** — 采用相同的提示格式、市场和文件夹结构 资料来源：[README.md]()
- **通用性** — 支持 Claude Code、Cursor、Windsurf、Aider、Codex 等多种代理 资料来源：[README.md]()
- **渐进式披露** — 按需加载技能，保持代理上下文的精简 资料来源：[README.md]()
- **仓库友好** — 技能与项目代码一同版本化管理 资料来源：[README.md]()
- **私有化友好** — 支持从本地路径或私有 Git 仓库安装技能 资料来源：[README.md]()
## 技术架构
### 技术栈
OpenSkills 基于现代 Node.js 生态构建，对运行环境有明确要求：
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Node.js | >= 20.6.0 | 项目引擎要求 |
| Git | 任意版本 | 用于克隆仓库 |
| TypeScript | 5.9.3 | 开发语言 |
| Vitest | 4.0.3 | 测试框架 |
**核心依赖库：**
| 库名 | 版本 | 用途 |
|------|------|------|
| commander | ^12.1.0 | CLI 命令框架 |
| chalk | ^5.6.2 | 终端着色 |
| ora | ^9.0.0 | 加载动画 |
| @inquirer/prompts | ^7.9.0 | 交互式提示 |
资料来源：[package.json]()
### 项目结构
```
openskills/
├── src/
│ ├── cli.ts # CLI 主入口，定义命令路由
│ ├── commands/ # 各命令实现
│ │ ├── update.ts # 技能更新逻辑
│ │ ├── install.ts # 技能安装逻辑
│ │ └── ...
│ ├── utils/ # 共享工具
│ │ ├── agents-md.ts # AGENTS.md 生成
│ │ └── ...
│ └── types.ts # TypeScript 接口定义
├── tests/ # 测试套件（88+ 测试用例）
├── examples/
│ └── my-first-skill/ # 示例技能
└── package.json
```
资料来源：[CONTRIBUTING.md]()
### 工作流程
```mermaid
graph TD
A[用户执行 CLI 命令] --> B{npx openskills}
B --> C[install 安装技能]
B --> D[sync 同步 AGENTS.md]
B --> E[list 列出技能]
B --> F[read 读取技能内容]
B --> G[update 更新技能]
B --> H[manage/remove 管理技能]
C --> C1[解析安装源]
C1 --> C2{GitHub 仓库?}
C2 -->|是| C3[git clone 克隆仓库]
C2 -->|否| C4{本地路径?}
C4 -->|是| C5[使用本地目录]
C4 -->|否| C6[私有 Git 仓库]
C3 --> C7[复制到技能目录]
C5 --> C7
C6 --> C7
C7 --> C8[写入元数据]
F --> F1[定位 SKILL.md]
F1 --> F2[输出技能内容]
F2 --> F3[提供基础目录]
```
## CLI 命令体系
### 命令总览
| 命令 | 描述 | 主要选项 |
|------|------|----------|
| `install ` | 从 GitHub/Git URL 安装技能 | `--global`, `--universal`, `--yes` |
| `sync` | 更新 AGENTS.md | `--yes`, `--output ` |
| `list` | 列出已安装技能 | - |
| `read ` | 读取技能内容到 stdout | - |
| `update [skill-names]` | 更新已安装技能 | - |
| `manage` | 交互式管理技能 | - |
| `remove ` | 移除指定技能 | - |
资料来源：[src/cli.ts]()
### 安装来源类型
OpenSkills 支持多种安装来源，覆盖了典型的使用场景：
| 来源类型 | 示例 | 说明 |
|----------|------|------|
| Anthropic 市场 | `anthropics/skills` | 从 Anthropic 官方技能库安装 |
| GitHub 仓库 | `your-org/your-skills` | 从任意 GitHub 仓库安装 |
| 本地路径 | `./local-skills/my-skill` | 从本地目录安装 |
| 私有仓库 | `git@github.com:org/private-skills.git` | 通过 SSH 安装私有仓库 |
资料来源：[README.md]()
### 安装位置优先级
```mermaid
graph LR
A[安装请求] --> B{--universal 标志?}
B -->|是| C[.agent/skills/]
B -->|否| D{--global 标志?}
D -->|是| E[~/.claude/skills/]
D -->|否| F[项目本地]
F --> G{存在 .claude/skills?}
G -->|是| H[./.claude/skills/]
G -->|否| I[./.agent/skills/]
C --> J[优先级 1: 最高]
H --> K[优先级 2]
E --> L[优先级 3]
I --> M[优先级 4]
```
优先级顺序：**`.agent/skills/` > `~/.agent/skills/` > `./.claude/skills/` > `~/.claude/skills/`**
资料来源：[README.md]()
## SKILL.md 格式规范
SKILL.md 是 OpenSkills 技能的核心文件，采用 YAML frontmatter + Markdown 的混合格式。
### 文件结构
```
skill-name/
├── SKILL.md # 必需：技能主文件
├── references/ # 可选：参考文档（按需加载）
├── scripts/ # 可选：可执行脚本
└── assets/ # 可选：资源文件（不加载到上下文）
```
资料来源：[examples/my-first-skill/references/skill-format.md]()
### YAML Frontmatter
每个 SKILL.md 必须以 YAML frontmatter 开头：
```yaml
---
name: skill-name # 必需：连字符格式标识符
description: When to use # 必需：1-2 句话描述，第三人称
---
```
### 内容写作规范
**推荐风格：**
- 使用祈使句/不定式："To accomplish X, execute Y"
- 被动表述："This skill is loaded when Z"
- 引用资源："See references/guide.md for details"
**应避免：**
- 第二人称："You should do X"
- 条件式："If you need Y"
资料来源：[examples/my-first-skill/references/skill-format.md]()
### 文件大小指南
| 部分 | 限制 | 说明 |
|------|------|------|
| SKILL.md | < 5,000 词 | 核心指令，保持精简 |
| references/ | 无限制 | 按需选择性加载 |
| scripts/ | 可执行 | 不计入上下文大小 |
| assets/ | 任意 | 不加载到上下文 |
资料来源：[examples/my-first-skill/references/skill-format.md]()
## 渐进式披露机制
OpenSkills 实现了三级渐进式加载策略，优化 AI 代理的上下文使用效率：
```mermaid
graph TD
A[技能元数据] --> B[SKILL.md 核心指令]
A --> C[references/ 详细文档]
A --> D[scripts/ 可执行脚本]
B --> E[始终加载]
C --> F[按需加载]
D --> G[执行时调用]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#f3e5f5
style D fill:#e8f5e9
```
| 级别 | 内容 | 加载时机 | 说明 |
|------|------|----------|------|
| 1 | 元数据 | 始终在上下文中 | name + description |
| 2 | SKILL.md | 技能被调用时 | 核心指令流程 |
| 3 | references/ | 需要时 | 详细 API 文档、指南 |
资料来源：[examples/my-first-skill/references/skill-format.md]()
资料来源：[README.md]()
## AGENTS.md 集成
### 生成机制
`sync` 命令负责生成包含技能信息的 AGENTS.md 文件段：
```mermaid
graph LR
A[扫描技能目录] --> B[读取元数据]
B --> C[解析 SKILL.md]
C --> D[生成 XML 块]
D --> E[替换 AGENTS.md 内容]
```
生成的 XML 块结构：
```xml
...
pdf
PDF manipulation toolkit...
project
```
资料来源：[src/utils/agents-md.ts]()
### 输出配置
`sync` 命令支持自定义输出路径：
| 选项 | 说明 |
|------|------|
| `-o, --output ` | 指定输出文件路径（默认：AGENTS.md） |
| `-y, --yes` | 跳过交互式选择，同步所有技能 |
资料来源：[README.md]()
## 技能更新机制
update 命令支持三种来源类型的技能更新：
```mermaid
graph TD
A[update 命令] --> B{技能来源类型}
B --> C[本地类型 local]
B --> D[Git 类型 git]
B --> E[未知类型]
C --> C1{本地路径存在?}
C1 -->|否| C2[跳过 - 源缺失]
C1 -->|是| C3{SKILL.md 存在?}
C3 -->|否| C4[跳过 - 文件缺失]
C3 -->|是| C5[从本地目录复制]
D --> D1{元数据包含 repoUrl?}
D1 -->|否| D2[跳过 - 缺少仓库 URL]
D1 -->|是| D3[git clone 临时目录]
D3 --> D4[复制到技能目录]
E --> E1[输出警告]
style C5 fill:#c8e6c9
style D4 fill:#c8e6c9
```
**更新流程要点：**
1. **本地技能**：直接使用 `localPath` 指向的目录作为更新源
2. **Git 技能**：克隆到临时目录后复制内容
3. **缺少元数据**：跳过更新并输出警告
资料来源：[src/commands/update.ts]()
## 版本演进
### 版本历史
| 版本 | 发布日期 | 关键特性 |
|------|----------|----------|
| 1.0.0 | 2025-10-26 | 初始版本，核心 CLI 功能 |
| 1.1.0 | 2025-10-27 | README 完善，位置标签修复 |
| 1.2.0 | 2025-10-27 | 增加 `--universal` 标志，项目本地安装成为默认 |
| 1.2.1 | 2025-10-27 | 文档清理，移除重复部分 |
| 1.3.0 | 2025-11-12 | 本地路径安装、私有仓库支持、88+ 测试用例 |
| 1.3.1-1.3.2 | 2026-01 | 符号链接支持、可配置输出路径 |
| 1.4.0 | 2026-01-17 | README 澄清、项目本地默认说明 |
| 1.5.0 | 2026-01-17 | 完整功能集发布 |
资料来源：[CHANGELOG.md]()
### 里程碑特性
**v1.3.0 新增特性：**
- 本地技能开发工作流支持
- 损坏的符号链接自动跳过
- 可配置输出路径（`--output` 标志）
- 从本地目录安装技能
- 私有 Git 仓库支持（SSH/HTTPS）
- 完整的测试套件
**v1.2.0 重大变更：**
- 项目安装成为默认行为（之前是全局安装）
- 技能默认安装到 `./.claude/skills/`
资料来源：[CHANGELOG.md]()
## 测试体系
OpenSkills 采用 Vitest 作为测试框架，构建了多层次的测试覆盖：
| 测试类型 | 测试文件数 | 说明 |
|----------|------------|------|
| 单元测试 | 多个 | 符号链接检测、YAML 解析 |
| 集成测试 | 多个 | install、sync 命令 |
| E2E 测试 | 多个 | 完整 CLI 工作流 |
资料来源：[CHANGELOG.md]()
**测试命令：**
```bash
npm run test # 运行所有测试
npm run test:watch # 监听模式
npm run test:coverage # 覆盖率报告
```
资料来源：[CONTRIBUTING.md]()
## 与 MCP 的对比
| 方面 | Skills | MCP |
|------|--------|-----|
| 实现方式 | 静态文件 | 动态服务器 |
| 通信协议 | 无需网络 | 需要 MCP 服务器 |
| 上下文加载 | 按需渐进式 | 实时查询 |
| 跨代理兼容性 | 高 | 依赖 MCP 支持 |
| 适用场景 | 固定指令集 | 动态工具调用 |
**设计理念差异：**
- **MCP 面向动态工具** — 适合需要实时交互、数据获取的场景
- **Skills 面向静态指令** — 适合流程指导、领域知识、模板生成
资料来源：[README.md]()
## 快速开始
### 安装方式
```bash
# 通过 npx 运行（无需安装）
npx openskills install anthropics/skills
npx openskills sync
# 全局安装
npm install -g openskills
```
### 本地开发
```bash
# 克隆项目
git clone git@github.com:your-org/openskills.git
cd openskills
# 链接本地 CLI
npm link
# 测试安装
npx openskills install anthropics/skills/pdf-editor --project
npx openskills sync
npx openskills read pdf-editor
```
资料来源：[CONTRIBUTING.md]()
## 系统要求
| 要求 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | 20.6.0+ | 项目引擎限制 |
| Git | 任意版本 | 用于仓库克隆操作 |
资料来源：[README.md]()
## 开源许可
OpenSkills 采用 **Apache 2.0** 开源许可证。项目实现了 Anthropic 的 Agent Skills 规范规范，并在 README 中标注了 Attribution。
资料来源：[README.md]()
资料来源：[CONTRIBUTING.md]()
---
## 快速开始
### 相关页面
相关主题：[项目概述](#page-overview), [CLI命令参考](#page-cli-commands)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)
- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)
- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)
- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)
- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)
# 快速开始
本页面介绍如何快速上手 OpenSkills，包括环境准备、技能安装、AGENTS.md 同步以及基本使用流程。
## 系统要求
| 要求 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | 20.6.0+ | 核心运行环境 |
| Git | 任意版本 | 用于克隆技能仓库 |
> 资料来源：[package.json:23-24]()
## 安装 OpenSkills
OpenSkills 无需全局安装，可直接通过 `npx` 运行。
### 方式一：直接使用 npx（推荐）
```bash
npx openskills --version
```
### 方式二：全局安装（可选）
```bash
npm install -g openskills
```
> 资料来源：[README.md:1-5]()
## 安装技能包
### 从 Anthropic 市场安装
```bash
npx openskills install anthropics/skills
```
> 资料来源：[README.md:12-15]()
### 从 GitHub 仓库安装
```bash
npx openskills install your-org/your-skills
```
> 资料来源：[README.md:17-19]()
### 从本地路径安装
```bash
npx openskills install ./local-skills/my-skill
```
支持绝对路径、相对路径和波浪号展开路径。
> 资料来源：[CHANGELOG.md:25-30]()
### 从私有仓库安装
```bash
npx openskills install git@github.com:your-org/private-skills.git
```
OpenSkills 自动使用系统 SSH 密钥进行身份验证。
> 资料来源：[CHANGELOG.md:31-35]()
## 安装选项说明
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--global` | 全局安装到 `~/.claude/skills` | 禁用 |
| `--universal` | 安装到 `.agent/skills/` | 禁用 |
| `-y, --yes` | 跳过交互确认，用于 CI/CD | 禁用 |
| `-o, --output ` | 指定输出路径（sync 命令） | AGENTS.md |
> 资料来源：[README.md:48-55]()
### 安装位置优先级
当使用 `--universal` 选项时，安装目录优先级如下：
1. `./.agent/skills/`
2. `~/.agent/skills/`
3. `./.claude/skills/`
4. `~/.claude/skills/`
> 资料来源：[README.md:27-34]()
## 同步技能到 AGENTS.md
安装技能后，需要运行同步命令将技能信息写入 `AGENTS.md` 文件。
### 基本同步流程
```bash
npx openskills sync
```
同步过程会：
1. 扫描已安装的技能目录
2. 读取每个技能的 `SKILL.md` 元数据
3. 生成 `` XML 块
4. 更新目标 `AGENTS.md` 文件
> 资料来源：[src/commands/sync.ts:1-15]()
### 生成的文件格式
同步后的 `AGENTS.md` 包含以下结构：
```xml
skill-name
技能描述
project
```
> 资料来源：[src/utils/agents-md.ts:45-60]()
## 使用技能
### 查看已安装的技能
```bash
npx openskills list
```
> 资料来源：[README.md:57-60]()
### 读取技能内容
```bash
npx openskills read
```
例如读取 PDF 技能：
```bash
npx openskills read pdf
```
> 资料来源：[README.md:1-7]()
### 加载多个技能
```bash
npx openskills read skill-one,skill-two
```
> 资料来源：[README.md:1-7]()
## 工作流程图
```mermaid
graph TD
A[安装 OpenSkills] --> B[安装技能包]
B --> C[运行 sync 同步]
C --> D[AGENTS.md 已更新]
D --> E[AI 代理读取 AGENTS.md]
E --> F[根据任务调用 npx openskills read]
F --> G[技能内容加载到上下文]
G --> H[执行技能指令]
```
## 常用命令速查表
| 命令 | 功能 |
|------|------|
| `npx openskills install ` | 从指定源安装技能 |
| `npx openskills sync` | 同步技能到 AGENTS.md |
| `npx openskills list` | 列出已安装的技能 |
| `npx openskills read ` | 读取技能内容 |
| `npx openskills update [name]` | 更新已安装的技能 |
| `npx openskills remove ` | 移除指定技能 |
| `npx openskills manage` | 交互式管理技能 |
> 资料来源：[README.md:57-60]()
## 本地技能开发
### 创建最小技能结构
```
my-skill/
└── SKILL.md
```
### 带资源的技能结构
```
my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/
```
> 资料来源：[README.md:85-95]()
### 使用符号链接进行开发
```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
```
> 资料来源：[README.md:103-108]()
## SKILL.md 格式简介
每个技能必须包含 YAML 前置内容和 Markdown 正文：
```yaml
---
name: skill-name
description: 技能描述（1-2句话，第三人称）
---
# 技能标题
技能使用说明...
```
> 资料来源：[examples/my-first-skill/SKILL.md:1-15]()
## 下一步
- 查看 [SKILL.md 格式参考](examples/my-first-skill/references/skill-format.md) 了解完整格式规范
- 查看 [CHANGELOG.md](../../CHANGELOG.md) 了解版本更新历史
- 查看 [CONTRIBUTING.md](../../CONTRIBUTING.md) 了解贡献指南
---
## 系统架构
### 相关页面
相关主题：[CLI命令参考](#page-cli-commands), [SKILL.md格式规范](#page-skill-md-format)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [src/types.ts](https://github.com/numman-ali/openskills/blob/main/src/types.ts)
- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)
- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)
- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)
# 系统架构
## 概述
OpenSkills 是一个通用的 AI 代理技能管理系统，旨在为各种 AI 编码代理提供标准化的技能加载机制。该项目采用 TypeScript 开发，基于 Node.js 20.6+ 运行时运行，通过命令行界面（CLI）提供技能安装、同步和管理功能。
核心设计理念是实现与 Anthropic Claude Code 技能格式的完全兼容，同时支持跨平台、多代理环境使用。技能以 `SKILL.md` 文件为核心，配合可选的 `references/`、`scripts/` 和 `assets/` 目录形成完整的技能包结构。
## 架构分层
```
┌─────────────────────────────────────────────────────────────┐
│ CLI 交互层 (cli.ts) │
│ commander 解析命令 + chalk/ora 美化输出 │
├─────────────────────────────────────────────────────────────┤
│ 命令实现层 (commands/) │
│ install │ read │ sync │ list │ update │ manage │ remove │
├─────────────────────────────────────────────────────────────┤
│ 工具函数层 (utils/) │
│ agents-md.ts │ skills.ts │ yaml.ts │ symlink.ts │
├─────────────────────────────────────────────────────────────┤
│ 类型定义层 (types.ts) │
│ Skill │ SkillSourceMetadata │ ... │
└─────────────────────────────────────────────────────────────┘
```
### 核心依赖
| 依赖包 | 版本 | 用途 |
|--------|------|------|
| commander | ^12.1.0 | CLI 命令解析 |
| chalk | ^5.6.2 | 终端输出着色 |
| ora | ^9.0.0 | 加载动画 |
| @inquirer/prompts | ^7.9.0 | 交互式提示 |
| typescript | ^5.9.3 | 类型检查 |
| vitest | ^4.0.3 | 单元测试 |
资料来源：[package.json:1-25]()
## 命令模块设计
### 命令注册机制
CLI 采用 Commander.js 框架进行命令注册和参数解析。主入口文件 `src/cli.ts` 负责定义所有可用命令：
```typescript
program
.command('list')
.description('List all installed skills')
.action(listSkills);
program
.command('install ')
.description('Install skill from GitHub or Git URL')
.option('-g, --global', 'Install globally (default: project install)')
.option('-u, --universal', 'Install to .agent/skills/')
.option('-y, --yes', 'Skip interactive selection')
.action(installSkill);
```
资料来源：[src/cli.ts:1-50]()
### 支持的命令列表
| 命令 | 功能 | 选项 |
|------|------|------|
| `install ` | 从 GitHub/本地路径安装技能 | `--global`, `--universal`, `--yes` |
| `sync` | 同步技能到 AGENTS.md | `--yes`, `--output ` |
| `list` | 列出已安装的技能 | - |
| `read ` | 读取技能内容输出到终端 | - |
| `update [skill-names]` | 更新已安装的技能 | - |
| `manage` | 交互式管理（删除）技能 | - |
| `remove ` | 移除指定技能 | - |
## 数据模型
### 技能元数据结构
```typescript
interface Skill {
name: string; // 技能标识符（连字符格式）
description: string; // 技能描述（1-2句）
location: 'project' | 'global' | 'plugin';
}
```
资料来源：[src/types.ts]()
### 技能来源元数据
```typescript
interface SkillSourceMetadata {
source: string; // 原始安装来源
sourceType: 'git' | 'local';
repoUrl?: string; // Git 仓库 URL
subpath?: string; // 子目录路径
localPath?: string; // 本地路径
installedAt: string; // ISO 时间戳
}
```
资料来源：[src/commands/install.ts:80-100]()
## 技能安装流程
```mermaid
graph TD
A[install 命令] --> B{解析来源类型}
B -->|GitHub URL| C[克隆仓库]
B -->|本地路径| D[验证本地目录]
B -->|SSH URL| E[使用 SSH 克隆]
C --> F[扫描 SKILL.md 文件]
D --> F
E --> F
F --> G{检查冲突}
G -->|项目安装| H[复制到 .claude/skills/]
G -->|全局安装| I[复制到 ~/.claude/skills/]
G -->|通用安装| J[复制到 .agent/skills/]
H --> K[写入元数据]
I --> K
J --> K
K --> L[安装完成]
```
### 安装元数据构建逻辑
```typescript
function buildMetadataFromSource(
sourceInfo: InstallSourceInfo,
skillDir: string,
repoDir: string
): SkillSourceMetadata {
if (sourceInfo.sourceType === 'local') {
return buildLocalMetadata(sourceInfo, skillDir);
}
const subpath = relative(repoDir, skillDir);
return buildGitMetadata(sourceInfo, normalizedSubpath);
}
```
资料来源：[src/commands/install.ts:70-85]()
## AGENTS.md 同步机制
### XML 结构生成
`agents-md.ts` 负责生成兼容 Claude Code 的技能列表 XML：
```typescript
export function generateSkillsXml(skills: Skill[]): string {
const skillTags = skills
.map((s) => `
${s.name}
${s.description}
${s.location}
`)
.join('\n\n');
// 返回完整的 skills_system XML 块
}
```
资料来源：[src/utils/agents-md.ts:60-80]()
### AGENTS.md 模板结构
```xml
## Available Skills
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.
- Invoke: `npx openskills read ` (run in your shell)
- Only use skills listed in
${skillTags}
```
资料来源：[src/utils/agents-md.ts:1-30]()
### 内容替换策略
```mermaid
graph LR
A[读取 AGENTS.md] --> B{检测标记类型}
B -->|XML 标记| C[使用正则替换 skills_system 块]
B -->|HTML 注释| D[使用正则替换 TABLE 块]
C --> E[写入更新后的内容]
D --> E
```
替换逻辑支持两种标记格式以保证向后兼容：
- XML 格式：`...`
- HTML 注释格式：`...`
资料来源：[src/utils/agents-md.ts:40-55]()
## 技能更新机制
### 更新流程
```mermaid
graph TD
A[update 命令] --> B[读取技能元数据]
B --> C{判断来源类型}
C -->|local| D[验证本地路径存在]
C -->|git| E[克隆最新仓库]
D -->|路径缺失| F[跳过并警告]
D -->|路径有效| G[复制文件到安装目录]
E --> G
G --> H[更新 installedAt 时间戳]
H --> I[更新完成]
```
### 本地源处理
```typescript
if (metadata.sourceType === 'local') {
const localPath = metadata.localPath;
if (!localPath || !existsSync(localPath)) {
console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));
continue;
}
if (!existsSync(join(localPath, 'SKILL.md'))) {
console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing)`));
continue;
}
updateSkillFromDir(skill.path, localPath);
}
```
资料来源：[src/commands/update.ts:1-30]()
## 技能目录结构
### 安装优先级
系统支持多层级的技能安装目录，按优先级从高到低排列：
| 优先级 | 目录 | 说明 |
|--------|------|------|
| 1 | `./.agent/skills/` | 通用安装（多代理环境） |
| 2 | `~/.agent/skills/` | 用户级通用安装 |
| 3 | `./.claude/skills/` | 项目本地安装 |
| 4 | `~/.claude/skills/` | 全局安装 |
安装时使用 `--universal` 标志会将技能安装到 `.agent/skills/`，适用于同时使用 Claude Code 和其他代理（如 Cursor、Windsurf、Aider）的场景。
资料来源：[README.md]() 和 [src/cli.ts]()
### 技能包标准结构
```
skill-name/
├── SKILL.md # 必需：技能定义文件
├── references/ # 可选：参考文档（API 文档、详细指南）
├── scripts/ # 可选：可执行脚本（Python/Bash）
└── assets/ # 可选：静态资源（模板、图片）
```
## 错误处理机制
```typescript
// 错误处理流程
if (err.code === 'commander.unknownOption' || err.code === 'commander.invalidArgument') {
// 参数错误：Commander 已显示错误信息
process.exit(1);
}
// 其他错误
process.exit(err.exitCode || 1);
```
资料来源：[src/cli.ts:10-20]()
### 冲突检测
安装前会检查目标路径是否已存在技能：
```typescript
async function warnIfConflict(
skillName: string,
targetPath: string,
isProject: boolean,
skipPrompt = false
): Promise {
if (existsSync(targetPath)) {
if (skipPrompt) {
// 自动覆盖模式
}
// 交互式确认模式
}
return true;
}
```
资料来源：[src/commands/install.ts:95-110]()
## SKILL.md 格式规范
### YAML 前置元数据
每个技能必须以 YAML frontmatter 开头：
```yaml
---
name: skill-name # 必需：连字符格式标识符
description: 技能用途描述 # 必需：1-2句话，第三人称
---
```
### 渐进式加载策略
| 层级 | 内容 | 加载时机 |
|------|------|----------|
| 元数据层 | name + description | 始终在上下文中 |
| 技能说明层 | SKILL.md 内容 | 相关任务时加载 |
| 资源层 | references/ | 按需选择性加载 |
### 编写规范
- 使用祈使语气："To do X, execute Y"
- 避免第二人称："You should..." 改为 "执行..."
- SKILL.md 控制在 5000 词以内
- 详细内容移至 `references/` 目录
资料来源：[examples/my-first-skill/references/skill-format.md]()
## 测试覆盖
项目使用 Vitest 框架进行测试，测试套件包含：
| 测试类型 | 覆盖范围 |
|----------|----------|
| 单元测试 | 符号链接检测、YAML 解析 |
| 集成测试 | install、sync 命令 |
| 端到端测试 | 完整 CLI 工作流 |
运行测试命令：
```bash
npm run test # 运行所有测试
npm run test:watch # 监听模式
npm run test:coverage # 覆盖率报告
```
资料来源：[CONTRIBUTING.md]()
## 技术栈总结
| 层级 | 技术选型 | 理由 |
|------|----------|------|
| 运行时 | Node.js 20.6+ | 现代化异步特性支持 |
| 开发语言 | TypeScript 5.9 | 类型安全保证 |
| CLI 框架 | Commander 12 | 成熟的命令行解析 |
| 用户交互 | Inquirer 7 + Ora | 美观的交互体验 |
| 构建工具 | tsup 8 | 快速的 TypeScript 打包 |
| 测试框架 | Vitest 4 | 高性能的 Vite 集成测试 |
此架构设计确保了 OpenSkills 能够作为一个轻量级、跨平台、与 Claude Code 完全兼容的技能管理系统运行。
---
## CLI命令参考
### 相关页面
相关主题：[install命令详解](#page-install-command), [sync命令详解](#page-sync-command), [update命令详解](#page-update-command)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
- [src/commands/list.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/list.ts)
- [src/commands/read.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/read.ts)
- [src/commands/manage.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/manage.ts)
- [src/commands/remove.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/remove.ts)
- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)
- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
# CLI命令参考
OpenSkills 是一个为AI编码助手设计的通用技能加载工具，通过命令行接口（CLI）实现技能的安装、管理和同步功能。本页面详细介绍 OpenSkills CLI 的所有命令及其用法。
## 概述
OpenSkills CLI 提供了一套完整的命令，用于管理 AI 代理技能的生命周期。CLI 基于 Node.js 构建，使用 Commander.js 作为命令行参数解析框架，并集成了 Inquirer.js 用于交互式提示。 资料来源：[src/cli.ts:1-50]()
### 核心功能模块
| 模块 | 功能描述 |
|------|----------|
| `install` | 从各种来源安装技能（GitHub、本地路径、私有仓库） |
| `list` | 列出所有已安装的技能 |
| `read` | 读取技能内容并输出到标准输出 |
| `update` | 从源更新已安装的技能 |
| `sync` | 同步技能信息到 AGENTS.md 文件 |
| `manage` | 交互式管理技能（删除） |
| `remove` | 移除指定的技能 |
## 命令详解
### install - 安装技能
`install` 命令用于从多种来源安装 AI 技能到本地环境。
#### 基本语法
```bash
npx openskills install [options]
```
#### 参数与选项
| 参数/选项 | 类型 | 说明 |
|-----------|------|------|
| `` | 位置参数 | 安装来源（GitHub仓库、本地路径、Git URL） |
| `-g, --global` | 选项 | 全局安装到 `~/.claude/skills/` |
| `-u, --universal` | 选项 | 安装到 `.agent/skills/` 用于多代理环境 |
| `-y, --yes` | 选项 | 跳过交互确认，自动安装所有找到的技能 |
#### 安装来源类型
1. **Anthropic Marketplace**
```bash
npx openskills install anthropics/skills
```
2. **任意 GitHub 仓库**
```bash
npx openskills install your-org/your-skills
```
3. **本地路径**
```bash
npx openskills install ./local-skills/my-skill
```
4. **私有 Git 仓库**
```bash
npx openskills install git@github.com:your-org/private-skills.git
```
#### 安装行为流程
```mermaid
graph TD
A[install 命令执行] --> B{源类型判断}
B -->|GitHub| C[克隆远程仓库]
B -->|本地路径| D[验证本地路径存在]
B -->|私有仓库| E[使用SSH密钥克隆]
C --> F[定位 SKILL.md]
D --> F
E --> F
F --> G{安装位置判断}
G -->|项目级| H[安装到 .claude/skills/]
G -->|全局| I[安装到 ~/.claude/skills/]
G -->|通用| J[安装到 .agent/skills/]
H --> K[写入技能元数据]
I --> K
J --> K
K --> L[安装完成]
```
#### 元数据构建
安装过程中，系统会根据来源类型构建不同的元数据：
| 来源类型 | 元数据字段 |
|----------|------------|
| Git 来源 | `sourceType: 'git'`、`repoUrl`、`subpath`、`installedAt` |
| 本地来源 | `sourceType: 'local'`、`localPath`、`installedAt` |
资料来源：[src/commands/install.ts:1-80]()
---
### list - 列出技能
`list` 命令显示所有已安装的技能及其状态信息。
#### 基本语法
```bash
npx openskills list
```
#### 输出示例
```
📦 已安装技能
├── pdf [project] /path/to/project/.claude/skills/pdf
├── git-workflow [global] ~/.claude/skills/git-workflow
└── check-branch-first [project] /path/to/project/.claude/skills/check-branch-first
```
---
### read - 读取技能内容
`read` 命令将技能内容输出到标准输出，供 AI 代理读取。
#### 基本语法
```bash
npx openskills read
```
#### 参数说明
| 参数 | 类型 | 说明 |
|------|------|------|
| `` | 剩余参数 | 一个或多个技能名称，用空格分隔 |
#### 使用示例
```bash
# 读取单个技能
npx openskills read pdf
# 读取多个技能（逗号分隔）
npx openskills read foo,bar
# 读取多个技能（空格分隔）
npx openskills read pdf git-workflow check-branch
```
#### 输出格式
读取技能时，输出包含以下信息：
- **基础目录路径**：用于解析相对资源路径
- **完整 SKILL.md 内容**：包含技能指令和元数据
- **引用资源路径**：references/、scripts/、assets/ 的相对路径
---
### update - 更新技能
`update` 命令从原始源重新获取并更新已安装的技能。
#### 基本语法
```bash
npx openskills update [skill-names...]
```
#### 参数说明
| 参数 | 类型 | 说明 |
|------|------|------|
| `[skill-names...]` | 可选参数 | 指定要更新的技能名称，默认为全部 |
#### 更新流程
```mermaid
graph TD
A[update 命令执行] --> B{是否指定技能}
B -->|是| C[筛选目标技能]
B -->|否| D[加载所有技能]
C --> E{技能元数据检查}
D --> E
E -->|本地来源| F[验证本地路径存在]
E -->|Git 来源| G[克隆远程仓库]
F -->|路径无效| H[跳过并警告]
F -->|路径有效| I[复制 SKILL.md]
G --> J[定位子路径]
I --> K[更新 installedAt 时间戳]
J --> K
K --> L[更新完成]
H --> M[报告跳过列表]
```
#### 特殊处理
| 场景 | 处理方式 |
|------|----------|
| 本地源缺失 | 输出黄色警告并跳过 |
| SKILL.md 不存在 | 输出警告并跳过 |
| 缺少仓库 URL | 输出警告并跳过 |
| Git 克隆失败 | 显示错误信息 |
资料来源：[src/commands/update.ts:1-60]()
---
### sync - 同步到 AGENTS.md
`sync` 命令将已安装的技能信息生成为 `` XML 块，并插入或更新 AGENTS.md 文件。
#### 基本语法
```bash
npx openskills sync [options]
```
#### 选项说明
| 选项 | 说明 |
|------|------|
| `-y, --yes` | 跳过交互确认，同步所有技能 |
| `-o, --output ` | 指定输出文件路径（默认：AGENTS.md） |
#### 输出文件格式
```markdown
## Available Skills
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively...
How to use skills:
- Invoke: `npx openskills read ` (run in your shell)
- The skill content will load with detailed instructions...
pdf
Comprehensive PDF manipulation toolkit...
project
```
#### XML 标记说明
| 标记 | 说明 |
|------|------|
| `` | 根元素，包含优先级属性 |
| `` | 技能列表容器 |
| `` | 单个技能定义块 |
| `` | 技能名称（英文、中划线分隔） |
| `` | 技能描述（1-2句话） |
| `` | 安装位置（project/global） |
---
### manage - 交互式管理
`manage` 命令提供交互式界面用于管理已安装的技能。
#### 基本语法
```bash
npx openskills manage
```
#### 交互流程
1. 显示已安装技能列表
2. 提供多选界面选择要移除的技能
3. 确认后执行删除操作
4. 更新 AGENTS.md（如需要）
---
### remove - 移除技能
`remove` 命令直接移除指定的技能，无需交互确认。
#### 基本语法
```bash
npx openskills remove
```
#### 参数说明
| 参数 | 类型 | 说明 |
|------|------|------|
| `` | 位置参数 | 要移除的技能名称 |
#### 使用示例
```bash
npx openskills remove pdf
npx openskills remove git-workflow
```
---
## 安装优先级
当使用 `--universal` 选项或存在多个安装位置时，技能加载遵循以下优先级顺序（优先级高者优先）：
```mermaid
graph LR
A1[.agent/skills/] --> A[优先级 1]
A2[~/.agent/skills/] --> A
B1[.claude/skills/] --> B[优先级 2]
B2[~/.claude/skills/] --> B
A --> C[技能加载顺序]
B --> C
```
| 优先级 | 路径 | 用途 |
|--------|------|------|
| 1 | `./.agent/skills/` | 多代理通用设置 |
| 1 | `~/.agent/skills/` | 全局多代理设置 |
| 2 | `./.claude/skills/` | 项目级 Claude Code 设置 |
| 2 | `~/.claude/skills/` | 全局 Claude Code 设置 |
---
## 环境要求
| 要求 | 最低版本 |
|------|----------|
| Node.js | 20.6.0+ |
| Git | 任意版本 |
---
## 命令速查表
| 命令 | 用法 | 核心功能 |
|------|------|----------|
| `install` | `npx openskills install ` | 安装技能 |
| `list` | `npx openskills list` | 列出已安装技能 |
| `read` | `npx openskills read [,...]` | 读取技能内容 |
| `update` | `npx openskills update [name...]` | 更新技能 |
| `sync` | `npx openskills sync [-y] [-o ]` | 同步到 AGENTS.md |
| `manage` | `npx openskills manage` | 交互式管理 |
| `remove` | `npx openskills remove ` | 移除技能 |
---
## install命令详解
### 相关页面
相关主题：[CLI命令参考](#page-cli-commands), [数据存储与管理](#page-data-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)
- [src/utils/marketplace-skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/marketplace-skills.ts)
- [src/utils/yaml.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/yaml.ts)
- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)
# install命令详解
## 概述
`install` 是 OpenSkills 的核心命令之一，负责从各种来源安装技能（Skills）。该命令支持从 GitHub 仓库、本地路径、Git 远程仓库以及私有仓库安装技能，并自动处理技能元数据的存储和更新。
**功能范围：**
- 从 Anthropic Marketplace 安装预制技能
- 从任意 GitHub 仓库安装技能
- 从本地目录安装本地开发的技能
- 支持私有 Git 仓库安装（SSH/HTTPS）
- 自动检测并处理符号链接冲突
- 支持全局安装和项目级安装
**版本历史：**
- v1.0.0：初始发布
- v1.2.0：新增 `--universal` 标志
- v1.5.0：新增本地路径安装和私有仓库支持
资料来源：[package.json:3-24](https://github.com/numman-ali/openskills/blob/main/package.json)
---
## 命令语法
```bash
npx openskills install [options]
```
### 参数说明
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `` | string | 是 | 安装来源，可以是 GitHub 仓库、本地路径或 Git URL |
### 可用选项
| 选项 | 简写 | 类型 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--global` | `-g` | boolean | false | 全局安装到 `~/.claude/skills/` |
| `--universal` | `-u` | boolean | false | 安装到 `.agent/skills/` 用于多智能体环境 |
| `--yes` | `-y` | boolean | false | 跳过所有交互提示，自动确认 |
资料来源：[src/cli.ts:26-35](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
---
## 安装来源类型
OpenSkills 支持多种安装来源，命令会自动识别来源类型并采用相应的安装策略。
```mermaid
graph TD
A[install source] --> B{来源类型判断}
B -->|GitHub shorthand| C[marketplace-skills.ts]
B -->|本地路径| D[本地目录检测]
B -->|git@ URL| E[SSH 私有仓库]
B -->|https:// URL| F[HTTPS 私有仓库]
B -->|github.com URL| G[GitHub 完整 URL]
C --> H[从 Marketplace 获取]
D --> I[直接复制/Symlink]
E --> J[SSH 认证克隆]
F --> K[HTTPS 认证克隆]
G --> L[直接克隆]
```
### 1. Anthropic Marketplace
使用简写格式从 Anthropic 官方技能市场安装：
```bash
npx openskills install anthropics/skills
npx openskills install anthropics/skills/pdf-editor
```
资料来源：[README.md:30-32](https://github.com/numman-ali/openskills/blob/main/README.md)
### 2. GitHub 仓库
从任意 GitHub 仓库安装，支持完整 URL 或简写格式：
```bash
# 简写格式
npx openskills install owner/repo
npx openskills install owner/repo/path/to/skill
# 完整 URL 格式
npx openskills install https://github.com/owner/repo
```
### 3. 本地路径
支持绝对路径、相对路径和波浪号展开：
```bash
# 绝对路径
npx openskills install /path/to/my-skill
# 相对路径
npx openskills install ./local-skills/my-skill
npx openskills install ../my-skill
# 波浪号展开
npx openskills install ~/my-skills/skill
```
资料来源：[CHANGELOG.md:47-52](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)
### 4. 私有 Git 仓库
支持 SSH 和 HTTPS 两种认证方式：
```bash
# SSH 方式（使用系统 SSH 密钥）
npx openskills install git@github.com:your-org/private-skills.git
# HTTPS 方式（需要配置 Git 认证）
npx openskills install https://github.com/your-org/private-skills.git
```
资料来源：[CHANGELOG.md:53-58](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)
---
## 安装位置与优先级
OpenSkills 提供了多种安装位置选项，适用于不同的使用场景。
```mermaid
graph TD
A[install 命令] --> B{--universal?}
B -->|是| C[.agent/skills/]
B -->|否| D{--global?}
D -->|是| E[~/.claude/skills/]
D -->|否| F[项目安装]
F --> G{存在.claude?}
G -->|是| H[./.claude/skills/]
G -->|否| I[./.agent/skills/]
style C fill:#ff9999
style E fill:#99ccff
style H fill:#99ff99
style I fill:#99ff99
```
### 位置优先级（最高优先）
| 优先级 | 位置 | 说明 |
|--------|------|------|
| 1 | `./.agent/skills/` | 项目级通用目录（当 `.claude` 不存在时） |
| 2 | `./.claude/skills/` | 项目级 Claude Code 目录 |
| 3 | `~/.agent/skills/` | 用户级通用目录 |
| 4 | `~/.claude/skills/` | 用户级全局目录 |
资料来源：[README.md:44-51](https://github.com/numman-ali/openskills/blob/main/README.md)
---
## 工作流程
### 安装流程图
```mpx openskillsxy
graph LR
A[解析 source 参数] --> B{识别来源类型}
B -->|GitHub| C[获取仓库信息]
B -->|本地| D[验证本地路径]
B -->|Git URL| E[解析 Git URL]
C --> F[克隆或更新仓库]
D --> G[验证 SKILL.md 存在]
E --> H[执行 git clone]
F --> I[查找 SKILL.md]
G --> I
H --> I
I --> J[创建技能目录]
J --> K[复制/Symlink 文件]
K --> L[生成元数据]
L --> M[写入 metadata.json]
M --> N[输出安装成功信息]
```
### 详细步骤说明
1. **来源解析**
- 解析 `` 参数确定安装类型
- 提取仓库 URL、组织/仓库名、技能路径等信息
2. **获取技能**
- GitHub：通过 Git 克隆仓库
- 本地：验证路径存在且包含 SKILL.md
3. **元数据生成**
- 创建 `metadata.json` 记录安装来源
- 存储安装时间、来源类型、仓库 URL 等信息
4. **文件复制**
- 根据安装类型决定复制或创建符号链接
- 本地开发模式优先使用符号链接
资料来源：[src/commands/install.ts:50-150](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
---
## 元数据结构
每个已安装的技能都包含一个 `metadata.json` 文件，记录技能的来源和安装信息。
### 元数据字段
| 字段 | 类型 | 说明 | 来源类型 |
|------|------|------|----------|
| `source` | string | 原始安装命令参数 | 所有 |
| `sourceType` | string | 来源类型：`git` 或 `local` | 所有 |
| `repoUrl` | string | Git 仓库 URL | git |
| `subpath` | string | 技能在仓库中的子路径 | git |
| `localPath` | string | 本地路径 | local |
| `installedAt` | string | ISO 8601 安装时间戳 | 所有 |
### Git 来源元数据示例
```json
{
"source": "anthropics/skills/pdf-editor",
"sourceType": "git",
"repoUrl": "https://github.com/anthropics/skills",
"subpath": "pdf-editor",
"installedAt": "2026-01-20T10:30:00.000Z"
}
```
### 本地来源元数据示例
```json
{
"source": "./my-skill",
"sourceType": "local",
"localPath": "/Users/developer/projects/my-skill",
"installedAt": "2026-01-20T10:30:00.000Z"
}
```
资料来源：[src/commands/install.ts:100-120](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
---
## 冲突检测与处理
### Claude Code 市场冲突警告
当安装的技能名称与 Claude Code 原生插件市场冲突时，命令会发出警告：
```mermaid
graph TD
A[install skill-name] --> B{目标路径存在?}
B -->|是| C[检查是否为符号链接]
C -->|是| D{--yes 标志?}
C -->|否| E[警告：覆盖风险]
D -->|是| F[自动覆盖]
D -->|否| G[询问用户确认]
B -->|否| H[继续安装]
E --> G
```
### 冲突处理规则
| 情况 | 行为 |
|------|------|
| `--yes` 模式 | 自动覆盖，不提示 |
| 交互模式 | 询问用户确认 |
| 符号链接断开 | 优雅跳过，显示警告 |
资料来源：[src/commands/install.ts:160-180](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
---
## 与其他命令的协作
`install` 命令不独立工作，它与其他 OpenSkills 命令紧密配合：
```mermaid
graph LR
A[install] -->|安装技能| B[本地文件系统]
C[sync] -->|读取安装信息| B
C -->|生成 AGENTS.md| D[AGENTS.md]
E[update] -->|读取 metadata.json| B
E -->|更新技能| B
F[read] -->|加载技能内容| B
F -->|输出到 stdout| G[AI Agent]
H[list] -->|扫描安装目录| B
H -->|显示技能列表| I[终端]
```
| 命令 | 与 install 的关系 |
|------|-------------------|
| `sync` | 读取已安装技能，生成 AGENTS.md |
| `update` | 读取 metadata.json，从原来源更新 |
| `read` | 加载已安装技能的内容 |
| `list` | 显示所有已安装技能 |
资料来源：[src/cli.ts:20-45](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
---
## 使用示例
### 基础安装
```bash
# 从 Anthropic Marketplace 安装所有技能
npx openskills install anthropics/skills
# 安装单个技能
npx openskills install anthropics/skills/pdf-editor
# 从其他 GitHub 仓库安装
npx openskills install owner/custom-skills
```
### 项目级 vs 全局安装
```bash
# 项目级安装（默认）
npx openskills install anthropics/skills
# 安装到: ./.claude/skills/
# 全局安装
npx openskills install anthropics/skills --global
# 安装到: ~/.claude/skills/
```
### 多智能体环境安装
```bash
# 使用 --universal 标志
npx openskills install anthropics/skills --universal
# 安装到: ./.agent/skills/
# 可被 Claude Code、Cursor、Windsurf、Aider 等共用
```
### CI/CD 环境使用
```bash
# 使用 --yes 跳过所有交互
npx openskills install your-org/your-skills --yes
# 指定输出文件
npx openskills install your-org/your-skills --yes --output .ruler/AGENTS.md
```
### 本地开发工作流
```bash
# 克隆技能仓库到开发目录
git clone git@github.com:your-org/my-skills.git ~/dev/my-skills
# 创建符号链接进行开发
mkdir -p .claude/skills
ln -s ~/dev/my-skills/pdf-editor .claude/skills/pdf-editor
# 安装后更新
npx openskills update pdf-editor
```
资料来源：[README.md:54-66](https://github.com/numman-ali/openskills/blob/main/README.md)
---
## 依赖项
`install` 命令依赖以下核心依赖包：
| 依赖包 | 版本 | 用途 |
|--------|------|------|
| `commander` | ^12.1.0 | CLI 参数解析和命令定义 |
| `@inquirer/prompts` | ^7.9.0 | 交互式提示（冲突确认等） |
| `chalk` | ^5.6.2 | 终端彩色输出 |
| `ora` | ^9.0.0 | 加载动画 |
**系统要求：**
- Node.js >= 20.6.0
- Git（用于克隆仓库）
资料来源：[package.json:15-20](https://github.com/numman-ali/openskills/blob/main/package.json)
---
## 常见问题
### Q: 安装后技能没有出现在 list 中？
检查技能目录是否正确：
```bash
ls -la .claude/skills/ # 项目级
ls -la ~/.claude/skills/ # 全局
```
### Q: 如何安装私有仓库？
确保：
1. SSH 方式已配置 SSH 密钥
2. HTTPS 方式已配置 Git 凭证
```bash
# SSH 方式
git clone git@github.com:org/private-skills.git
# 验证 SSH 密钥
ssh -T git@github.com
```
### Q: 如何处理符号链接冲突？
使用 `--yes` 标志自动覆盖，或手动删除后重新安装：
```bash
rm -rf .claude/skills/conflicting-skill
npx openskills install owner/skill
---
## sync命令详解
### 相关页面
相关主题：[CLI命令参考](#page-cli-commands), [SKILL.md格式规范](#page-skill-md-format)
相关源码文件
以下源码文件用于生成本页说明：
- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)
- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [src/types.ts](https://github.com/numman-ali/openskills/blob/main/src/types.ts)
- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
# sync命令详解
`sync` 是 OpenSkills 的核心命令之一，用于将已安装的技能（Skills）同步到 `AGENTS.md` 文件中，生成可供 AI Agent 识别的 `` XML 区块。本文详细解析该命令的实现原理、工作流程和配置选项。
## 功能概述
`sync` 命令的主要职责是根据已安装技能的元数据，动态生成符合 Anthropic Agent Skills 规范的 XML 内容，并将其注入到 `AGENTS.md` 文件中。生成的 XML 遵循特定的优先级机制，支持渐进式加载（Progressive Disclosure）模式。
**核心功能：**
| 功能 | 描述 |
|------|------|
| 技能扫描 | 读取 `.claude/skills/` 或 `.agent/skills/` 目录下的已安装技能 |
| XML生成 | 生成包含 name、description、location 的 skill 标签 |
| 文件更新 | 将生成的 XML 区块替换或插入到目标 Markdown 文件 |
| 输出控制 | 支持自定义输出路径 |
资料来源：[src/cli.ts:35-38]()
## 命令行接口
### 基本语法
```bash
npx openskills sync [选项]
```
### 参数与选项
| 选项 | 简写 | 类型 | 默认值 | 描述 |
|------|------|------|--------|------|
| `--yes` | `-y` | 布尔 | `false` | 跳过交互式确认，同步所有技能 |
| `--output` | `-o` | 路径 | `AGENTS.md` | 指定输出文件路径 |
**使用示例：**
```bash
# 默认同步到 AGENTS.md
npx openskills sync
# 跳过交互确认
npx openskills sync -y
# 输出到自定义路径
npx openskills sync -o .ruler/AGENTS.md
```
资料来源：[src/cli.ts:42-45]()
## 工作流程
`sync` 命令的执行流程可分为三个主要阶段：
```mermaid
graph TD
A[启动 sync 命令] --> B[解析命令行参数]
B --> C{是否指定 -y?}
C -->|是| D[跳过交互式选择]
C -->|否| E[显示技能选择列表]
E --> F[用户选择要同步的技能]
D --> G[读取已安装技能元数据]
F --> G
G --> H[扫描 skills 目录]
H --> I[解析每个技能的 SKILL.md]
I --> J[生成 XML 内容]
J --> K[更新目标文件]
K --> L[输出完成信息]
```
### 阶段一：参数解析
CLI 框架（Commander.js）负责解析用户输入的选项。如果未指定 `-y` 标志，命令将启动交互式界面让用户选择要同步的技能。
资料来源：[src/cli.ts:42-45]()
### 阶段二：技能扫描与 XML 生成
系统会遍历指定的 skills 目录（默认为 `.claude/skills/`），读取每个技能目录下的 `SKILL.md` 文件，解析 YAML frontmatter 中的 `name` 和 `description` 字段。
生成的 XML 结构如下：
```xml
## Available Skills
当用户请求任务时，检查以下可用技能...
skill-name
技能描述
project
```
资料来源：[src/utils/agents-md.ts:55-85]()
### 阶段三：文件更新
`sync` 命令使用 `replaceSkillsSection` 函数处理目标文件。该函数支持两种标记格式：
1. **XML 标记格式**（首选）：
```html
...
```
2. **HTML 注释格式**（向后兼容）：
```html
...
```
函数会自动检测文件中存在的标记格式，并执行相应的替换操作。
资料来源：[src/utils/agents-md.ts:88-110]()
## 核心实现
### agents-md.ts 工具模块
该模块提供了三个核心函数：
#### `parseCurrentSkills(content: string): string[]`
解析 `AGENTS.md` 文件中当前已列出的技能名称：
```typescript
const skillRegex = /[\s\S]*?([^<]+)<\/name>[\s\S]*?<\/skill>/g;
```
正则表达式匹配 `` 标签块，提取其中的 `` 元素值。
资料来源：[src/utils/agents-md.ts:113-122]()
#### `generateSkillsXml(skills: Skill[]): string`
根据技能数组生成完整的 XML 区块：
```typescript
export function generateSkillsXml(skills: Skill[]): string {
const skillTags = skills
.map(
(s) => `
${s.name}
${s.description}
${s.location}
`
)
.join('\n\n');
// ... 生成完整 XML 结构
}
```
每个技能生成独立的 `` 标签块，包含三个子元素：
- ``：技能标识符
- ``：技能描述
- ``：安装位置（`project` 或 `global`）
资料来源：[src/utils/agents-md.ts:125-148]()
#### `replaceSkillsSection(content: string, newSection: string): string`
执行实际的文件替换操作：
```typescript
export function replaceSkillsSection(content: string, newSection: string): string {
const startMarker = ']*>[\s\S]*?<\/skills_system>/;
return content.replace(regex, newSection);
}
// ... 处理 HTML 注释格式
}
```
函数首先尝试使用 XML 标记进行匹配和替换，如果失败则回退到 HTML 注释格式。
资料来源：[src/utils/agents-md.ts:88-110]()
### Skill 数据模型
```typescript
interface Skill {
name: string; // 技能标识符
description: string; // 技能描述
location: string; // 安装位置：'project' | 'global'
}
```
资料来源：[src/types.ts]()
## 与 update 命令的协同
`sync` 命令与 `update` 命令存在密切配合关系。当用户执行 `npx openskills update` 时，更新后的技能元数据会被重新写入，此时可以使用 `sync` 命令将更新后的技能信息同步到 `AGENTS.md`：
```bash
# 更新所有技能后同步
npx openskills update
npx openskills sync
```
`update` 命令支持更新本地路径安装的技能：
```typescript
if (metadata.sourceType === 'local') {
const localPath = metadata.localPath;
if (!existsSync(localPath)) {
console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));
continue;
}
updateSkillFromDir(skill.path, localPath);
writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });
}
```
资料来源：[src/commands/update.ts:89-102]()
## 输出文件格式
`sync` 命令生成的文件采用固定的模板结构，包含以下部分：
| 部分 | 描述 |
|------|------|
| `` | 根元素，包含 `priority="1"` 属性 |
| `` | 使用说明文本，指导 AI Agent 如何调用技能 |
| `` | 技能列表容器 |
| `` | 单个技能定义块 |
**生成的完整结构示例：**
```xml
## Available Skills
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
How to use skills:
- Invoke: `npx openskills read ` (run in your shell)
- For multiple: `npx openskills read skill-one,skill-two`
- The skill content will load with detailed instructions
- Base directory provided in output for resolving bundled resources
Usage notes:
- Only use skills listed in below
- Do not invoke a skill that is already loaded in your context
pdf
Comprehensive PDF manipulation toolkit...
project
```
资料来源：[src/utils/agents-md.ts:55-85]()
## 配置选项详解
### 输出路径配置
`sync` 命令支持通过 `-o` 或 `--output` 选项指定输出文件路径：
| 输入 | 输出位置 |
|------|----------|
| `npx openskills sync` | `./AGENTS.md` |
| `npx openskills sync -o .ruler/AGENTS.md` | `./.ruler/AGENTS.md` |
| `npx openskills sync -o /absolute/path/file.md` | `/absolute/path/file.md` |
**特殊功能：**
- **自动创建目录**：如果指定的输出路径包含不存在的目录，系统会自动创建
- **自动创建文件**：如果目标文件不存在，系统会创建文件并添加标题
- **自动创建区块**：如果文件中不存在 `` 区块，系统会自动插入
资料来源：[src/cli.ts:42-45]()
### 非交互模式
使用 `-y` 或 `--yes` 标志可以跳过所有交互式确认，直接同步所有已安装的技能：
```bash
# CI/CD 环境推荐用法
npx openskills sync -y
```
此模式适用于自动化脚本和持续集成环境。
## 最佳实践
### 1. 定期同步
建议在以下时机执行 `sync` 命令：
| 时机 | 原因 |
|------|------|
| 安装新技能后 | 确保新技能被 AI Agent 识别 |
| 移除技能后 | 清理 AGENTS.md 中的过时信息 |
| 更新技能描述后 | 同步最新的技能元数据 |
### 2. 多代理环境配置
在同时使用 Claude Code 和其他 Agent（如 Cursor、Windsurf）的环境中，推荐使用 `--universal` 标志安装技能到 `.agent/skills/` 目录：
```bash
npx openskills install your-org/your-skills --universal
npx openskills sync -o .agent/AGENTS.md
```
这样可以避免与 Claude Code 原生插件市场的冲突。
### 3. 版本控制建议
将 `AGENTS.md` 纳入版本控制，确保团队成员获得一致的技能配置。
## 错误处理
`sync` 命令可能遇到的错误场景及处理方式：
| 错误场景 | 处理方式 |
|----------|----------|
| 目标目录不存在 | 自动创建目录结构 |
| 目标文件只读 | 报错并提示修改权限 |
| skills 目录为空 | 生成空的 `` 区块 |
| YAML 解析失败 | 跳过该技能，显示警告信息 |
## 相关命令
| 命令 | 功能 | 关系 |
|------|------|------|
| `install` | 安装技能到本地 | sync 依赖已安装的技能 |
| `update` | 更新技能版本 | 与 sync 配合使用 |
| `list` | 列出已安装技能 | 提供参考信息 |
| `read` | 读取技能内容 | AI Agent 实际调用技能 |
## 总结
`sync` 命令是 OpenSkills 生态系统的关键连接点，它将本地安装的技能与 AI Agent 的上下文系统桥接起来。通过解析已安装技能的元数据并生成符合规范的 XML 内容，该命令使得 AI Agent 能够在需要时动态加载相应的技能指导。
核心要点：
- 使用 `-o` 选项支持灵活的输出路径配置
- `-y` 标志实现完全非交互式同步
- 支持 XML 和 HTML 注释两种标记格式
- 自动处理文件创建和目录结构
---
## update命令详解
### 相关页面
相关主题：[install命令详解](#page-install-command), [数据存储与管理](#page-data-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)
- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)
- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
# update命令详解
## 概述
`update` 命令是 OpenSkills 提供的核心功能之一，用于从已记录的源代码刷新已安装的技能（Skills）。该命令在 v1.5.0 版本中引入，解决了用户安装技能后如何获取更新的问题。
### 核心功能
- 从 Git 仓库更新技能
- 从本地目录更新技能
- 批量更新所有已安装的技能
- 跳过无法确定源代码的技能并给出提示
资料来源：[CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)
---
## 架构设计
### 模块依赖关系
```mermaid
graph TD
A[CLI入口 update命令] --> B[commands/update.ts]
B --> C[skill-metadata.ts]
B --> D[skills.ts]
B --> E[文件系统操作]
C --> F[SkillSourceMetadata接口]
C --> G[元数据读写]
D --> H[技能目录扫描]
D --> I[SKILL.md解析]
E --> J[git clone]
E --> K[文件复制]
```
### 元数据结构
```typescript
interface SkillSourceMetadata {
source: string; // 安装源描述
sourceType: 'git' | 'local'; // 源类型
repoUrl?: string; // Git仓库URL (git类型)
subpath?: string; // 子路径 (git类型)
localPath?: string; // 本地路径 (local类型)
installedAt: string; // 安装时间ISO字符串
}
```
资料来源：[src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)
---
## 工作流程
### 更新流程图
```mermaid
graph TD
Start[开始更新] --> LoadSkills[加载所有已安装技能]
LoadSkills --> ForEach{遍历每个技能}
ForEach --> |本地源| CheckLocalPath{检查localPath是否存在}
CheckLocalPath --> |不存在| SkipMissing[跳过并提示缺失]
SkipMissing --> Next1[下一个技能]
CheckLocalPath --> |存在| CheckSkillMd{检查SKILL.md}
CheckSkillMd --> |不存在| SkipNoSkillMd[跳过并提示SKILL.md缺失]
SkipNoSkillMd --> Next2[下一个技能]
CheckSkillMd --> |存在| CopyFromLocal[从本地复制文件]
CopyFromLocal --> UpdateMeta[更新元数据installedAt]
UpdateMeta --> Next3[下一个技能]
ForEach --> |Git源| CheckRepoUrl{检查repoUrl}
CheckRepoUrl --> |不存在| SkipNoUrl[跳过并提示缺失repoUrl]
SkipNoUrl --> Next4[下一个技能]
CheckRepoUrl --> |存在| CloneTemp[克隆到临时目录]
CloneTemp --> ExtractSource[提取子目录源文件]
ExtractSource --> CopyToTarget[复制到技能目录]
CopyToTarget --> UpdateMeta2[更新元数据installedAt]
UpdateMeta2 --> Next5[下一个技能]
Next1 --> |完成| Cleanup[清理临时目录]
Next2 --> Cleanup
Next3 --> Cleanup
Next4 --> Cleanup
Next5 --> Cleanup
Cleanup --> Report[输出更新结果统计]
```
---
## 源码解析
### 命令注册
`update` 命令通过 Commander.js 在 CLI 入口点注册：
```typescript
program
.command('update [skill-names...]')
.description('Update installed skills from their source (default: all)')
.action(updateSkills);
```
资料来源：[src/cli.ts:51-53](https://github.com/numman-ali/openskills/blob/main/src/cli.ts#L51-L53)
### 本地源更新逻辑
当技能源类型为 `local` 时，执行以下流程：
```typescript
if (metadata.sourceType === 'local') {
const localPath = metadata.localPath;
// 检查本地路径是否存在
if (!localPath || !existsSync(localPath)) {
console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));
missingLocalSource.push(skill.name);
skipped++;
continue;
}
// 检查SKILL.md是否存在
if (!existsSync(join(localPath, 'SKILL.md'))) {
console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing at local source)`));
missingLocalSkillFile.push(skill.name);
skipped++;
continue;
}
// 执行更新
updateSkillFromDir(skill.path, localPath);
writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });
console.log(chalk.green(`✅ Updated: ${skill.name}`));
updated++;
}
```
资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
### Git源更新逻辑
当技能源类型为 `git` 时，执行以下流程：
```mermaid
sequenceDiagram
participant User as 用户
participant Update as update命令
participant FS as 文件系统
participant Git as Git
User->>Update: 执行 update 命令
Update->>FS: 创建临时目录 ~/.openskills-temp-{timestamp}
Update->>Git: git clone --depth 1 {repoUrl}
Git-->>FS: 克隆到 tempDir/repo
Update->>FS: 提取子目录文件
Update->>FS: 复制到技能安装目录
Update->>FS: 更新元数据 (installedAt)
Update->>FS: 清理临时目录
Update->>User: 输出更新结果
```
关键实现代码：
```typescript
if (!metadata.repoUrl) {
console.log(chalk.yellow(`Skipped: ${skill.name} (missing repo URL metadata)`));
missingRepoUrl.push(skill.name);
skipped++;
continue;
}
const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
mkdirSync(tempDir, { recursive: true });
const spinner = ora(`Updating ${skill.name}...`).start();
try {
execSync(`git clone --depth 1 --quiet "${metadata.repoUrl}" "${tempDir}/repo"`, {
stdio: 'pipe'
});
const repoDir = join(tempDir, 'repo');
const subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';
const sourceDir = subpath ? join(repoDir, subpath) : repoDir;
// 继续处理...
} finally {
// 清理临时目录
}
```
资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
---
## 使用方法
### 基本语法
```bash
npx openskills update [skill-names...]
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| skill-names | string[] | 否 | 要更新的技能名称，不提供则更新所有技能 |
### 使用场景
#### 更新所有技能
```bash
# 更新所有已安装的技能
npx openskills update
```
#### 更新指定技能
```bash
# 更新单个技能
npx openskills update pdf
# 更新多个技能
npx openskills update pdf,git-workflow,check-branch-first
```
---
## 输出示例
### 成功更新
```
✅ Updated: pdf
✅ Updated: git-workflow
✅ Updated: check-branch-first
更新完成: 3 个技能已更新
```
### 跳过技能
```
Skipped: some-skill (missing repo URL metadata)
⚠️ 1 个技能跳过（无源代码信息）
```
### 输出统计
```typescript
// 更新完成后显示统计
console.log(`\n✅ 更新完成: ${updated} 个技能已更新`);
if (skipped > 0) {
console.log(`⚠️ ${skipped} 个技能跳过`);
console.log('提示: 重新安装技能以获取源代码信息');
}
```
资料来源：[src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
---
## 错误处理
### 错误类型与处理策略
| 错误类型 | 处理策略 | 用户提示 |
|----------|----------|----------|
| 本地源路径不存在 | 跳过 | `Skipped: {name} (local source missing)` |
| 本地源缺少SKILL.md | 跳过 | `Skipped: {name} (SKILL.md missing at local source)` |
| Git仓库URL缺失 | 跳过 | `Skipped: {name} (missing repo URL metadata)` |
| Git克隆失败 | 标记失败 | 显示错误信息 |
| 文件复制失败 | 标记失败 | 显示错误信息 |
### 临时目录清理
更新完成后，无论成功与否，都会清理临时目录：
```typescript
finally {
if (existsSync(tempDir)) {
rmSync(tempDir, { recursive: true, force: true });
}
}
```
---
## 相关配置
### 元数据存储位置
每个技能的元数据存储在 `~/.claude/skills/{skill-name}/.skill-metadata.json` 或 `./.claude/skills/{skill-name}/.skill-metadata.json` 文件中。
### 完整元数据接口
```typescript
interface SkillSourceMetadata {
source: string; // 原始安装源
sourceType: 'git' | 'local'; // 源类型
repoUrl?: string; // Git仓库地址 (git类型必须)
subpath?: string; // 仓库中的子路径
localPath?: string; // 本地绝对路径 (local类型必须)
installedAt: string; // 安装时间 (ISO 8601格式)
}
```
资料来源：[src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)
---
## 版本历史
| 版本 | 发布日期 | 变更内容 |
|------|----------|----------|
| 1.5.0 | 2026-01-17 | 新增 `openskills update` 命令，支持从源代码刷新已安装技能 |
| 1.5.0 | 2026-01-17 | 新增源元数据跟踪功能，为更新提供可靠依据 |
资料来源：[CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)
---
## 最佳实践
1. **定期更新**：建议在开始新项目前运行 `npx openskills update` 获取最新技能
2. **版本控制**：将技能目录加入版本控制可以追踪技能版本变化
3. **本地开发**：使用符号链接（symlink）可以在开发时实时测试技能更新
4. **批量处理**：不传参数时自动更新所有技能，适合定期维护
---
## SKILL.md格式规范
### 相关页面
相关主题：[项目概述](#page-overview), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [examples/my-first-skill/SKILL.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/SKILL.md)
- [examples/my-first-skill/references/skill-format.md](https://github.com/numman-ali/openskills/blob/main/examples/my-first-skill/references/skill-format.md)
- [src/utils/agents-md.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/agents-md.ts)
- [README.md](https://github.com/numman-ali/openskills/blob/main/README.md)
- [CHANGELOG.md](https://github.com/numman-ali/openskills/blob/main/CHANGELOG.md)
# SKILL.md格式规范
## 概述
SKILL.md是OpenSkills项目的核心技能描述格式，它采用Anthropic提出的智能体技能（Agent Skills）规范。该格式基于Markdown语法，结合YAML元数据前端块，用于定义AI编码智能体在执行特定任务时应加载的技能指令和资源文件。
SKILL.md的设计理念是实现**渐进式披露（Progressive Disclosure）**，即根据任务需要动态加载不同详细程度的技能信息，而非一次性将所有内容加载到智能体上下文中。这种方式有效控制了上下文窗口的占用，同时保证了技能使用的灵活性。
资料来源：[examples/my-first-skill/references/skill-format.md:1-25]()
## 文件结构
### 最小化结构
一个基础的SKILL.md技能只需要一个目录和主文件：
```
my-skill/
└── SKILL.md
```
### 完整结构
包含完整资源的技能应包含以下目录结构：
```
skill-name/
├── SKILL.md # 核心指令文档（约2,000字）
├── references/ # 参考文档目录
│ ├── api-docs.md # API详细文档
│ └── guide.md # 使用指南
├── scripts/ # 可执行脚本目录
│ ├── helper.sh # Shell脚本
│ └── process.py # Python脚本
└── assets/ # 静态资源目录
└── template.pdf # 模板文件
```
资料来源：[examples/my-first-skill/references/skill-format.md:60-75]()
### 目录职责
| 目录 | 用途 | 加载到上下文 | 计数限制 |
|------|------|-------------|---------|
| `references/` | 详细API文档、数据库schema、指南 | 按需加载 | 无限制 |
| `scripts/` | Python/Bash等可执行代码 | 不加载 | 不计入字数 |
| `assets/` | 模板、图片等输出文件 | 不加载 | 不计入字数 |
资料来源：[examples/my-first-skill/references/skill-format.md:45-60]()
## YAML前端块规范
每个SKILL.md文件必须以YAML前端块开始，该块用于定义技能的基本元数据。
### 必需字段
```yaml
---
name: skill-name # 必需：连字符分隔的标识符
description: When to use # 必需：1-2句话的第三人称描述
---
```
### 字段说明
| 字段 | 类型 | 必填 | 格式要求 | 示例 |
|------|------|------|----------|------|
| `name` | string | 是 | 小写字母、连字符 | `pdf-editor`、`git-workflow` |
| `description` | string | 是 | 第三人称、1-2句 | `Comprehensive PDF manipulation toolkit...` |
### 命名规范
- 仅使用小写字母
- 使用连字符（`-`）分隔单词
- 避免使用下划线或驼峰命名
- 名称应简洁且具有描述性
资料来源：[examples/my-first-skill/references/skill-format.md:3-12]()
## Markdown正文规范
### 语气要求
正文内容应使用**祈使句/不定式形式**编写，避免使用第二人称。
**推荐写法：**
```markdown
To accomplish X, execute Y
Load this skill when Z
See references/guide.md for details
```
**应避免的写法：**
```markdown
You should do X
If you need Y, you should...
When you want Z, you can...
```
### 段落结构
建议按以下顺序组织内容：
1. **标题** - 使用技能名称作为主标题
2. **目的说明** - 简要说明技能用途
3. **使用场景** - 何时应加载此技能
4. **执行步骤** - 完成任务的具体指令
5. **资源引用** - 指向bundled resources的链接
资料来源：[examples/my-first-skill/SKILL.md:1-40]()
## 渐进式披露机制
SKILL.md采用三级渐进式信息披露机制，智能体根据任务需求动态加载不同层级的信息。
```mermaid
graph TD
A[任务请求] --> B{技能匹配}
B -->|匹配成功| C[Level 1: 元数据]
B -->|需要核心指令| D[Level 2: SKILL.md]
B -->|需要详细文档| E[Level 3: Resources]
C --> F[name + description]
D --> G[核心指令步骤]
E --> H[references/]
E --> I[scripts/]
style C fill:#90EE90
style D fill:#87CEEB
style E fill:#DDA0DD
```
### 三级加载机制
| 级别 | 内容 | 何时加载 | 上下文占用 |
|------|------|----------|-----------|
| **Level 1** | 元数据（name + description） | 始终在上下文中 | 极小 |
| **Level 2** | SKILL.md核心指令 | 技能被请求时 | 中等 |
| **Level 3** | resources资源文件 | 按需加载 | 可变 |
资料来源：[examples/my-first-skill/references/skill-format.md:20-30]()
## 文件大小限制
为保证技能加载效率和上下文管理，OpenSkills对不同类型的文件设定了大小限制：
| 文件类型 | 建议大小 | 限制 | 说明 |
|----------|----------|------|------|
| SKILL.md | ~2,000字 | < 5,000字 | 核心指令应保持简洁 |
| references/ | 无限制 | 无限制 | 按需选择性加载 |
| scripts/ | 可执行 | 不计数 | 不加载到上下文 |
| assets/ | 无限制 | 无限制 | 仅作为输出使用 |
资料来源：[examples/my-first-skill/references/skill-format.md:35-50]()
## 资源解析机制
当技能被加载时，OpenSkills会提供基础目录路径，技能内的相对路径应从该基础目录解析。
### 资源解析示例
```
Base directory: /path/to/my-first-skill
```
相对路径解析规则：
| 相对路径 | 解析结果 |
|----------|----------|
| `references/skill-format.md` | `/path/to/my-first-skill/references/skill-format.md` |
| `scripts/helper.sh` | `/path/to/my-first-skill/scripts/helper.sh` |
| `assets/template.pdf` | `/path/to/my-first-skill/assets/template.pdf` |
资料来源：[examples/my-first-skill/SKILL.md:55-65]()
## AGENTS.md集成
OpenSkills通过生成特定的XML格式实现与AGENTS.md的集成。技能信息以``块的形式嵌入到AGENTS.md中。
### 生成格式
```xml
pdf
Comprehensive PDF manipulation toolkit...
plugin
```
### 使用方式
当AI智能体需要使用技能时，应通过以下命令加载：
```bash
npx openskills read
```
对于多个技能，使用逗号分隔：
```bash
npx openskills read skill-one,skill-two
```
资料来源：[src/utils/agents-md.ts:1-50]()
## 最佳实践
### 编写规范
1. **使用祈使语气** - 直接描述操作而非建议
2. **保持简洁** - SKILL.md应聚焦核心指令，细节移至references
3. **明确触发条件** - 说明何时应加载此技能
4. **引用资源** - 使用相对路径引用bundled resources
### 结构建议
```
skill/
├── SKILL.md # 简洁的核心指令
├── references/ # 详细文档
│ ├── api.md # API参考
│ └── schemas.md # 数据结构
└── scripts/ # 辅助脚本
```
### 常见错误
| 错误类型 | 问题 | 修正方式 |
|----------|------|----------|
| 第二人称 | "You should do X" | 改为 "To do X, execute Y" |
| 过长内容 | SKILL.md超过5000字 | 将详细文档移至references/ |
| 路径错误 | 使用绝对路径 | 使用相对于基础目录的相对路径 |
| 命名不当 | `mySkillName` | 改为 `my-skill-name` |
资料来源：[examples/my-first-skill/SKILL.md:30-50]()
## 完整示例
```markdown
---
name: pdf-editor
description: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms.
---
# PDF Editor Skill
## Purpose
This skill provides comprehensive PDF manipulation capabilities.
## When to Use
Load this skill when:
- Extracting text from PDF documents
- Merging or splitting PDF files
- Creating new PDFs from scratch
- Working with PDF forms
## Instructions
To accomplish PDF tasks:
1. Install dependencies: `pip install pypdf2`
2. Extract text using scripts/extract_text.py
3. Use references/api-docs.md for detailed API information
## Bundled Resources
- `references/api-docs.md` - Complete API documentation
- `references/format-guide.md` - PDF format specifications
- `scripts/extract_text.py` - Text extraction utility
- `scripts/merge_pdfs.py` - PDF merging tool
## Best Practices
- Always verify PDF encoding before processing
- Use batch processing for large document sets
- Handle password-protected files with appropriate permissions
```
资料来源：[examples/my-first-skill/references/skill-format.md:1-95]()
## 命令行工具集成
OpenSkills提供了一系列命令行工具用于管理SKILL.md格式的技能：
| 命令 | 功能 |
|------|------|
| `npx openskills install ` | 从GitHub或本地路径安装技能 |
| `npx openskills sync` | 同步技能列表到AGENTS.md |
| `npx openskills list` | 列出已安装的技能 |
| `npx openskills read ` | 读取技能内容供智能体使用 |
| `npx openskills update` | 从源更新已安装的技能 |
| `npx openskills remove ` | 移除指定技能 |
资料来源：[README.md:50-80]()
## 技术实现
### 文件解析流程
```mermaid
graph LR
A[SKILL.md文件] --> B[YAML解析器]
B --> C[YAML前端块]
C --> D{验证必需字段}
D -->|name| E[提取技能名称]
D -->|description| F[提取描述]
B --> G[Markdown解析器]
G --> H[核心指令内容]
H --> I[上下文注入]
style A fill:#f9f
style I fill:#9f9
```
### 元数据存储
技能元数据以JSON格式存储在`.claude/skills/`或`.agent/skills/`目录中：
```json
{
"source": "anthropics/skills",
"sourceType": "git",
"repoUrl": "https://github.com/anthropics/skills",
"subpath": "pdf-editor",
"installedAt": "2025-01-15T10:30:00Z"
}
```
资料来源：[src/commands/install.ts:1-50]()
---
## 数据存储与管理
### 相关页面
相关主题：[install命令详解](#page-install-command), [update命令详解](#page-update-command)
相关源码文件
以下源码文件用于生成本页说明：
- [src/utils/dirs.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/dirs.ts)
- [src/utils/skills.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skills.ts)
- [src/utils/skill-metadata.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-metadata.ts)
- [src/utils/skill-names.ts](https://github.com/numman-ali/openskills/blob/main/src/utils/skill-names.ts)
- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
- [src/commands/sync.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/sync.ts)
# 数据存储与管理
OpenSkills 的数据存储与管理模块负责管理技能的安装位置、元数据持久化、技能发现机制以及与 `AGENTS.md` 的同步功能。该模块确保技能能够被正确安装、定位、追踪来源，并在 AI 代理需要时提供可用技能列表。
## 目录结构
OpenSkills 采用分层目录结构存储技能数据，支持项目级别和全局级别的安装。
```mermaid
graph TD
A[用户项目] --> B[.claude/skills/]
A --> C[.agent/skills/]
D[用户主目录] --> E[~/.claude/skills/]
B --> F[skill-name/]
C --> G[skill-name/]
E --> H[skill-name/]
F --> I[SKILL.md]
F --> J[metadata.json]
G --> K[SKILL.md]
G --> K2[metadata.json]
H --> L[SKILL.md]
H --> L2[metadata.json]
```
### 目录层级与优先级
| 位置 | 路径 | 说明 | 优先级 |
|------|------|------|--------|
| 项目目录 | `./.claude/skills/` | 项目本地安装（默认） | 最高 |
| 通用目录 | `./.agent/skills/` | 使用 `--universal` 参数 | 高 |
| 用户目录 | `~/.claude/skills/` | 全局安装（需 `-g` 参数） | 低 |
资料来源：[src/utils/dirs.ts]()
### 目录路径解析
```typescript
// 技能目录名称常量
export const SKILLS_DIR_NAME = '.claude';
export const SKILLS_SUBDIR = 'skills';
// 获取技能安装根目录
export function getSkillsRoot(isGlobal: boolean): string {
if (isGlobal) {
return join(homedir(), SKILLS_DIR_NAME, SKILLS_SUBDIR);
}
return join(process.cwd(), SKILLS_DIR_NAME, SKILLS_SUBDIR);
}
```
资料来源：[src/utils/dirs.ts:1-20]()
## 元数据管理
每个已安装的技能都包含一个 `metadata.json` 文件，用于记录技能的来源和安装信息。
### 元数据结构
```typescript
interface SkillSourceMetadata {
source: string; // 原始安装源
sourceType: 'git' | 'local'; // 源类型
repoUrl?: string; // Git 仓库 URL（git 类型）
subpath?: string; // 仓库内子路径（git 类型）
localPath?: string; // 本地路径（local 类型）
installedAt: string; // ISO 格式安装时间
}
```
资料来源：[src/commands/install.ts:80-95]()
### 元数据写入
```typescript
function writeSkillMetadata(skillPath: string, metadata: SkillSourceMetadata): void {
const metadataPath = join(skillPath, 'metadata.json');
writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
}
```
资料来源：[src/commands/install.ts:120-125]()
### 元数据用途
元数据主要用于以下场景：
1. **更新技能**：通过 `openskills update` 命令重新拉取最新版本
2. **来源追溯**：了解技能的原始安装位置
3. **冲突检测**：避免与 Claude Code 插件市场产生冲突
资料来源：[src/commands/install.ts:127-145]()
## 技能发现机制
技能发现是定位系统中所有已安装技能的核心功能。
### 技能发现流程
```mermaid
graph TD
A[开始查找技能] --> B[检查 .claude/skills/]
B --> C{存在?}
C -->|是| D[遍历子目录]
C -->|否| E[返回空列表]
D --> F{包含 SKILL.md?}
F -->|是| G[添加技能到列表]
F -->|否| H[跳过目录]
G --> I{还有更多目录?}
I -->|是| D
I -->|否| J[检查全局目录 ~/.claude/skills/]
J --> K{存在?}
K -->|是| L[遍历子目录]
K -->|否| M[返回所有发现的技能]
L --> F2{SKILL.md?}
F2 -->|是| G2[添加技能到列表]
F2 -->|否| H2[跳过]
G2 --> I2{还有更多?}
I2 -->|是| L
I2 -->|否| M[返回技能列表]
```
### 技能查找实现
```typescript
export function findAllSkills(): Skill[] {
const skills: Skill[] = [];
// 检查项目目录
const projectDir = join(process.cwd(), '.claude', 'skills');
if (existsSync(projectDir)) {
skills.push(...findSkillsInDir(projectDir, 'project'));
}
// 检查全局目录
const globalDir = join(homedir(), '.claude', 'skills');
if (existsSync(globalDir)) {
skills.push(...findSkillsInDir(globalDir, 'global'));
}
return skills;
}
```
资料来源：[src/utils/skills.ts:10-35]()
### 技能目录遍历
```typescript
function findSkillsInDir(baseDir: string, location: 'project' | 'global'): Skill[] {
const skills: Skill[] = [];
const entries = readdirSync(baseDir, { withFileTypes: true });
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const skillPath = join(baseDir, entry.name);
const skillMdPath = join(skillPath, 'SKILL.md');
// 跳过符号链接指向不存在的路径
if (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {
continue;
}
if (existsSync(skillMdPath)) {
const skill = parseSkillInfo(skillPath, location);
if (skill) {
skills.push(skill);
}
}
}
return skills;
}
```
资料来源：[src/utils/skills.ts:40-65]()
### 符号链接处理
OpenSkills 在本地开发工作流中支持符号链接。被破坏的符号链接会被优雅地跳过，不会导致错误：
```typescript
// 跳过断裂的符号链接
if (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {
continue;
}
```
资料来源：[src/utils/skills.ts:50-52]()
## 技能信息解析
### SKILL.md 文件解析
```typescript
export function parseSkillInfo(skillPath: string, location: 'project' | 'global'): Skill | null {
const skillMdPath = join(skillPath, 'SKILL.md');
const content = readFileSync(skillMdPath, 'utf-8');
// 解析 YAML frontmatter
const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
if (!frontmatterMatch) {
return null;
}
const frontmatter = parseFrontmatter(frontmatterMatch[1]);
const name = frontmatter.name || basename(skillPath);
const description = frontmatter.description || '';
return { name, description, path: skillPath, location };
}
```
资料来源：[src/utils/skills.ts:70-95]()
### Frontmatter 解析
```typescript
function parseFrontmatter(yaml: string): Record {
const result: Record = {};
const lines = yaml.split('\n');
for (const line of lines) {
const match = line.match(/^(\w+):\s*(.+)$/);
if (match) {
result[match[1]] = match[2].trim();
}
}
return result;
}
```
资料来源：[src/utils/skills.ts:100-115]()
## AGENTS.md 同步管理
`AGENTS.md` 是 AI 代理读取技能列表的关键文件，sync 命令负责维护其中的技能列表。
### 同步数据流
```mermaid
graph LR
A[技能目录] --> B[findAllSkills]
B --> C[Skill 对象数组]
C --> D[generateSkillsXml]
D --> E[ XML]
E --> F[replaceSkillsSection]
F --> G[AGENTS.md 文件]
```
### 技能 XML 生成
```typescript
export function generateSkillsXml(skills: Skill[]): string {
const skillTags = skills
.map(
(s) => `
${s.name}
${s.description}
${s.location}
`
)
.join('\n\n');
// 完整的 skills_system XML 结构
return `
...
${skillTags}
`;
}
```
资料来源：[src/utils/agents-md.ts:50-80]()
### 当前技能解析
```typescript
export function parseCurrentSkills(content: string): string[] {
const skillNames: string[] = [];
const skillRegex = /[\s\S]*?([^<]+)<\/name>[\s\S]*?<\/skill>/g;
let match;
while ((match = skillRegex.exec(content)) !== null) {
skillNames.push(match[1].trim());
}
return skillNames;
}
```
资料来源：[src/utils/agents-md.ts:85-100]()
### 交互式同步选择
sync 命令支持交互式选择界面：
```typescript
// 排序：项目级别优先
const sorted = skills.sort((a, b) => {
if (a.location !== b.location) {
return a.location === 'project' ? -1 : 1;
}
return a.name.localeCompare(b.name);
});
// 预选当前文件中已存在的技能
const choices = sorted.map((skill) => ({
name: `${skill.name} ${skill.location === 'project' ? '(project)' : '(global)'}`,
value: skill.name,
description: skill.description.slice(0, 70),
checked: currentSkills.includes(skill.name) ||
(currentSkills.length === 0 && skill.location === 'project'),
}));
```
资料来源：[src/commands/sync.ts:45-65]()
## 技能来源类型
### Git 来源
从 GitHub 仓库安装的技能存储以下信息：
| 字段 | 说明 | 示例 |
|------|------|------|
| `source` | 原始安装命令参数 | `anthropics/skills/pdf` |
| `sourceType` | 固定值 `'git'` | `git` |
| `repoUrl` | 完整仓库 URL | `https://github.com/anthropics/skills` |
| `subpath` | 仓库内的子目录路径 | `pdf` |
| `installedAt` | ISO 时间戳 | `2025-10-27T10:30:00.000Z` |
资料来源：[src/commands/install.ts:80-95]()
### 本地来源
从本地路径安装的技能存储以下信息：
| 字段 | 说明 | 示例 |
|------|------|------|
| `source` | 原始安装命令参数 | `./my-skills/pdf` |
| `sourceType` | 固定值 `'local'` | `local` |
| `localPath` | 绝对路径 | `/Users/dev/my-skills/pdf` |
| `installedAt` | ISO 时间戳 | `2025-10-27T10:30:00.000Z` |
资料来源：[src/commands/install.ts:97-107]()
### 元数据构建
```typescript
function buildMetadataFromSource(
sourceInfo: InstallSourceInfo,
skillDir: string,
repoDir: string
): SkillSourceMetadata {
if (sourceInfo.sourceType === 'local') {
return buildLocalMetadata(sourceInfo, skillDir);
}
const subpath = relative(repoDir, skillDir);
const normalizedSubpath = subpath === '' ? '' : subpath;
return buildGitMetadata(sourceInfo, normalizedSubpath);
}
```
资料来源：[src/commands/install.ts:70-85]()
## 技能更新机制
更新功能利用存储的元数据重新拉取技能：
```mermaid
graph TD
A[update 命令] --> B[读取 metadata.json]
B --> C{检查 sourceType}
C -->|local| D[验证 localPath 存在]
C -->|git| E[克隆 repoUrl 仓库]
D --> F{SKILL.md 存在?}
E --> G[复制文件到技能目录]
F -->|是| H[从 localPath 复制]
F -->|否| I[跳过并警告]
G --> J[更新 installedAt]
H --> J
J --> K[更新完成]
I --> K
```
### 本地技能更新
```typescript
if (metadata.sourceType === 'local') {
const localPath = metadata.localPath;
if (!existsSync(localPath)) {
console.log(chalk.yellow(`Skipped: ${skill.name} (local source missing)`));
continue;
}
if (!existsSync(join(localPath, 'SKILL.md'))) {
console.log(chalk.yellow(`Skipped: ${skill.name} (SKILL.md missing at local source)`));
continue;
}
updateSkillFromDir(skill.path, localPath);
writeSkillMetadata(skill.path, { ...metadata, installedAt: new Date().toISOString() });
}
```
资料来源：[src/commands/update.ts:10-35]()
### Git 技能更新
```typescript
const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
mkdirSync(tempDir, { recursive: true });
// 克隆仓库（浅克隆，仅获取最新）
execSync(`git clone --depth 1 --quiet "${metadata.repoUrl}" "${tempDir}/repo"`, { stdio: 'pipe' });
const repoDir = join(tempDir, 'repo');
const subpath = metadata.subpath && metadata.subpath !== '.' ? metadata.subpath : '';
const sourceDir = subpath ? join(repoDir, subpath) : repoDir;
```
资料来源：[src/commands/update.ts:40-55]()
## 数据模型汇总
### Skill 接口
```typescript
interface Skill {
name: string; // 技能名称（必需）
description: string; // 技能描述（必需）
path: string; // 技能文件系统路径
location: 'project' | 'global'; // 安装位置
}
```
### InstallSourceInfo 接口
```typescript
interface InstallSourceInfo {
source: string;
sourceType: 'git' | 'local';
repoUrl?: string;
localPath?: string;
isUrl: boolean;
skillName: string;
skillDir: string;
}
```
### AGENTS.md 输出结构
```xml
## Available Skills
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.
...
pdf
Comprehensive PDF manipulation toolkit...
project
```
资料来源：[src/utils/agents-md.ts:1-50]()
## 文件清单
| 文件路径 | 职责 |
|---------|------|
| `src/utils/dirs.ts` | 定义目录路径常量和获取函数 |
| `src/utils/skills.ts` | 技能发现、解析、遍历逻辑 |
| `src/utils/skill-metadata.ts` | 元数据读写操作 |
| `src/utils/skill-names.ts` | 技能名称相关工具函数 |
| `src/commands/install.ts` | 安装命令中的元数据构建逻辑 |
| `src/commands/sync.ts` | AGENTS.md 同步命令实现 |
| `src/utils/agents-md.ts` | AGENTS.md XML 生成和解析 |
## 最佳实践
1. **项目级别优先**：默认使用项目级别安装，便于版本控制和团队协作
2. **元数据完整性**：安装后检查 `metadata.json` 确保信息正确
3. **符号链接开发**：本地开发时使用符号链接避免重复复制
4. **定期同步**：更新技能后执行 `npx openskills sync` 保持 AGENTS.md 最新
5. **冲突预防**：使用 `--universal` 参数避免与 Claude Code 插件市场冲突
---
## 贡献指南
### 相关页面
相关主题：[项目概述](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [CONTRIBUTING.md](https://github.com/numman-ali/openskills/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/numman-ali/openskills/blob/main/package.json)
- [src/cli.ts](https://github.com/numman-ali/openskills/blob/main/src/cli.ts)
- [src/commands/install.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/install.ts)
- [src/commands/update.ts](https://github.com/numman-ali/openskills/blob/main/src/commands/update.ts)
# 贡献指南
本文档为希望参与 OpenSkills 项目开发的贡献者提供完整的开发指南，涵盖开发环境配置、代码规范、测试流程以及提交流程等内容。
## 项目概述
OpenSkills 是一个跨平台的多代理技能管理系统，兼容 Anthropic 的 Agent Skills 规范，支持 Claude Code、Cursor、Windsurf、Aider、Codex 等多种 AI 编码代理工具。项目使用 Node.js 20.6.0+ 作为运行时环境，通过 TypeScript 实现，依赖包括 Commander.js 用于 CLI 框架、Chalk 用于终端着色、Ora 用于加载动画、Inquirer 用于交互式提示。 资料来源：[package.json:1-25]()
## 开发环境配置
### 环境要求
| 组件 | 最低版本 | 说明 |
|------|---------|------|
| Node.js | 20.6.0+ | 运行时环境 |
| Git | 任意版本 | 用于代码版本管理和依赖安装 |
| npm | 与 Node.js 捆绑 | 包管理器 |
资料来源：[package.json:23]()
### 安装步骤
```bash
# 克隆项目
git clone https://github.com/numman-ali/openskills.git
cd openskills
# 安装依赖
npm install
```
### 本地链接与测试
开发过程中可以使用 `npm link` 将本地包链接到全局，使 CLI 命令在本地可用：
```bash
npm link
```
链接后即可在任意目录下使用 `openskills` 命令：
```bash
npx openskills install anthropics/skills/pdf-editor --project
npx openskills sync
npx openskills read pdf-editor
```
资料来源：[CONTRIBUTING.md:1-10]()
## 项目结构
```
openskills/
├── src/
│ ├── cli.ts # CLI 主入口，定义命令行接口
│ ├── commands/ # 各子命令实现
│ │ ├── install.ts # 安装技能命令
│ │ └── update.ts # 更新技能命令
│ ├── utils/ # 共享工具函数
│ │ └── agents-md.ts # AGENTS.md 生成工具
│ └── types.ts # TypeScript 类型定义
├── tests/
│ └── utils/ # 单元测试
├── package.json
├── tsconfig.json
└── vitest.config.ts
```
### 核心模块职责
| 模块 | 职责 |
|------|------|
| cli.ts | 定义所有 CLI 命令及参数解析 |
| commands/install.ts | 处理技能安装逻辑，包括本地路径、私有仓库、GitHub 等多种来源 |
| commands/update.ts | 实现技能更新逻辑，支持从源仓库拉取最新内容 |
| utils/agents-md.ts | 生成符合规范的 `` XML 区块 |
| types.ts | 定义 Skill、SkillSourceMetadata 等核心数据结构 |
资料来源：[CONTRIBUTING.md:18-24]()
## 开发命令
### 运行测试
```bash
# 运行所有测试
npm run test
# 监听模式（文件变化自动重跑）
npm run test:watch
# 生成覆盖率报告
npm run test:coverage
```
OpenSkills 使用 Vitest 作为测试框架，测试文件位于 `tests/utils/` 目录。测试覆盖包括符号链接检测、YAML 解析、install 命令集成测试、sync 命令集成测试以及完整的 E2E CLI 工作流测试。
资料来源：[CONTRIBUTING.md:4-6]()
### 构建项目
```bash
npm run build
```
构建输出通过 tsup 处理，将 TypeScript 编译为 JavaScript 并生成类型声明文件。
### 代码检查与格式化
项目使用 TypeScript 编译器进行类型检查：
```bash
npm run lint # 代码风格检查
npm run format # 代码格式化
```
## CLI 命令参考
### 主要命令列表
| 命令 | 功能 | 主要参数 |
|------|------|----------|
| `npx openskills install ` | 从 GitHub、本地路径或私有仓库安装技能 | `-g, --global`、`-u, --universal`、`-y, --yes` |
| `npx openskills sync` | 更新 AGENTS.md 中的技能列表 | `-y, --yes`、`-o, --output ` |
| `npx openskills list` | 列出所有已安装的技能 | - |
| `npx openskills read ` | 读取技能内容输出到终端 | - |
| `npx openskills update [names...]` | 更新已安装的技能 | - |
| `npx openskills manage` | 交互式管理技能（删除） | - |
| `npx openskills remove ` | 删除指定技能 | - |
资料来源：[src/cli.ts:19-46]()
### 安装命令详解
```bash
# 从 GitHub 安装
npx openskills install anthropics/skills
# 从本地路径安装
npx openskills install ./local-skills/my-skill
# 从私有仓库安装
npx openskills install git@github.com:your-org/private-skills.git
# 全局安装
npx openskills install anthropics/skills --global
# 通用模式（多代理环境）
npx openskills install anthropics/skills --universal
# 非交互模式（CI/CD）
npx openskills install anthropics/skills --yes
```
安装流程会创建符号链接到指定目录（默认为 `./.claude/skills/`），并生成元数据文件记录安装来源信息，便于后续更新。
资料来源：[CONTRIBUTING.md:7-10]()
### 同步命令详解
```bash
# 同步到默认 AGENTS.md
npx openskills sync
# 指定输出文件
npx openskills sync -o .ruler/AGENTS.md
# 非交互模式
npx openskills sync --yes
```
sync 命令会扫描已安装技能的 SKILL.md 文件，提取 name、description、location 等元数据，生成符合 Anthropic 规范的 `` XML 区块并写入目标文件。
资料来源：[src/utils/agents-md.ts:45-70]()
## 代码提交规范
### 提交信息格式
```
<类型>: <简短描述>
[可选的详细说明]
```
### 提交类型
| 类型 | 用途 |
|------|------|
| `feat` | 新功能 |
| `fix` | 错误修复 |
| `docs` | 文档更新 |
| `test` | 测试相关 |
| `refactor` | 代码重构 |
| `chore` | 构建或辅助工具变更 |
### 提交前检查清单
- [ ] 所有测试通过 `npm run test`
- [ ] 代码符合 TypeScript 类型检查
- [ ] 新功能包含相应的测试用例
- [ ] 更新了相关文档（如有 API 变更）
## 问题报告指南
报告问题时，请确保包含以下信息：
| 信息项 | 说明 |
|--------|------|
| 问题类型 | Bug 报告或功能请求 |
| 复现步骤 | 详细的操作步骤 |
| 版本信息 | `npx openskills --version` 输出 |
| Node.js 版本 | `node --version` 输出 |
| 预期行为 | 希望看到的正确行为 |
| 实际行为 | 当前观察到的行为 |
资料来源：[CONTRIBUTING.md:26-32]()
## 许可协议
通过向 OpenSkills 项目提交贡献，您同意您的贡献将按照 Apache 2.0 许可证授权。贡献者无需签署任何额外的贡献者许可协议。
资料来源：[CONTRIBUTING.md:34]()
## 技能开发指南
OpenSkills 兼容 Anthropic 的 SKILL.md 格式。开发新技能时，需要遵循以下结构：
```bash
my-skill/
├── SKILL.md # 主技能文件（必需）
├── references/ # 参考文档目录
├── scripts/ # 可执行脚本目录
└── assets/ # 静态资源目录
```
### SKILL.md 格式要求
```yaml
---
name: skill-name # 必需：小写连字符格式
description: 何时使用此技能 # 必需：1-2句话描述
---
```
### 技能安装与测试
```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
# 测试技能
npx openskills read my-skill
```
资料来源：[CONTRIBUTING.md:11-17]()
## 技术架构流程
### 技能安装流程
```mermaid
graph TD
A[用户执行 install 命令] --> B{来源类型}
B -->|GitHub| C[解析 org/repo 格式]
B -->|本地路径| D[验证本地目录存在]
B -->|SSH URL| E[使用系统 SSH 密钥克隆]
C --> F[克隆远程仓库]
D --> G[复制本地技能]
E --> F
F --> H[扫描仓库中的 SKILL.md]
G --> H
H --> I[写入元数据]
I --> J[创建符号链接]
J --> K[安装完成]
H -->|多个技能| I
```
### 技能更新流程
```mermaid
graph TD
A[用户执行 update 命令] --> B{技能元数据类型}
B -->|local| C[验证本地路径存在]
B -->|git| D[克隆源仓库]
C --> E[从本地路径复制更新]
D --> F[从子路径提取技能]
E --> G[更新技能文件]
F --> G
G --> H[更新元数据 installedAt]
H --> I[更新完成]
```
更新流程会检查本地源路径是否存在、SKILL.md 文件是否完整，然后执行文件同步并更新元数据中的安装时间戳。
资料来源：[src/commands/update.ts:1-30]()
## 获取帮助
| 渠道 | 用途 |
|------|------|
| GitHub Issues | 功能请求、Bug 报告 |
| GitHub Discussions | 贡献相关问题、架构讨论 |
| Anthropic 文档 | SKILL.md 规范参考 |
资料来源：[CONTRIBUTING.md:33-37]()
---
---
## Doramagic 踩坑日志
项目：numman-ali/openskills
摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`。
## 1. 安装坑 · 来源证据：[BUG] `--universal` installs to `.agent/` not `.agents/`
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] `--universal` installs to `.agent/` not `.agents/`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c384eba59a4f4177ace0a344b94400dc | https://github.com/numman-ali/openskills/issues/84 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] add cli option --skills=name1,name2 to only install selected skill from github repo non-interactivelly
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3ec834575446429c96f39db392b81751 | https://github.com/numman-ali/openskills/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 来源证据：[Feature]: Read skill.json from source repos for install and sync
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Read skill.json from source repos for install and sync
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8752343cfb2d4231a5eb42f242806a31 | https://github.com/numman-ali/openskills/issues/81 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 安全/权限坑 · 来源证据：[BUG] Update command doesn't update all paths
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Update command doesn't update all paths
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8f8a414bbe634c229bf200f45014fc57 | https://github.com/numman-ali/openskills/issues/75 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：[BUG] Clone failed
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Clone failed
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_59fb2f76bd674cf2bba0efb5a57843bd | https://github.com/numman-ali/openskills/issues/85 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：[BUG] EEXIST when overwriting an existing skill during installation
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] EEXIST when overwriting an existing skill during installation
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ac382f17e8a744b58f7d0860617a2f19 | https://github.com/numman-ali/openskills/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：v1.2.0 - Universal Skills Support
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Universal Skills Support
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_31f11650e29a4e7c9fbd4ff026d577d0 | https://github.com/numman-ali/openskills/releases/tag/v1.2.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 8. 安装坑 · 来源证据：v1.2.1 - Documentation Fixes
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.1 - Documentation Fixes
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bb36323b2acd470bb0382644fddfde5f | https://github.com/numman-ali/openskills/releases/tag/v1.2.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 9. 安装坑 · 来源证据：v1.5.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.5.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7fab452932ab47e18a1d915b327b22d2 | https://github.com/numman-ali/openskills/releases/tag/v1.5.0 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1083829346 | https://github.com/numman-ali/openskills | README/documentation is current enough for a first validation pass.
## 11. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | last_activity_observed missing
## 12. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1083829346 | https://github.com/numman-ali/openskills | no_demo; severity=medium
## 14. 安全/权限坑 · 来源证据：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Path Resolution & Sandbox Access Conflict for Global OpenSkills on macOS
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_92230b03d1ec434694ad8d2e5ee6441f | https://github.com/numman-ali/openskills/issues/87 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 15. 安全/权限坑 · 来源证据：[FEATURE] Explicit local-first precedence for synced skills
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Explicit local-first precedence for synced skills
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6a14016c475349378139fe37f465945b | https://github.com/numman-ali/openskills/issues/86 | 来源类型 github_issue 暴露的待验证使用条件。
## 16. 安全/权限坑 · 来源证据：[FEATURE] Remote path that isn't a git repo
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Remote path that isn't a git repo
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_24fd46302500414a80566af028da3bb8 | https://github.com/numman-ali/openskills/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。
## 17. 安全/权限坑 · 来源证据：v1.1.0 - Comprehensive Documentation & Location Tag Fix
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.1.0 - Comprehensive Documentation & Location Tag Fix
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_315e89cc6fa641ceaf797b3c8a4a6f6e | https://github.com/numman-ali/openskills/releases/tag/v1.1.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 18. 安全/权限坑 · 来源证据：v1.3.0 - CI/CD, Local Development & Security
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.0 - CI/CD, Local Development & Security
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d2fade5f1d8e4e3080b89bdeb9d7bc3f | https://github.com/numman-ali/openskills/releases/tag/v1.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 19. 安全/权限坑 · 来源证据：v1.3.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.3.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_aa1710ddf10a42069b3e12cf5b4eb65a | https://github.com/numman-ali/openskills/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 20. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | issue_or_pr_quality=unknown
## 21. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1083829346 | https://github.com/numman-ali/openskills | release_recency=unknown