项目定位与核心价值

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 生态构建，对运行环境有明确要求：

核心依赖库：

资料来源：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

工作流程

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 命令体系

命令总览

资料来源：src/cli.ts

安装来源类型

OpenSkills 支持多种安装来源，覆盖了典型的使用场景：

资料来源：README.md

安装位置优先级

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 开头：

系统要求

资料来源：package.json:23-24

安装 OpenSkills

OpenSkills 无需全局安装，可直接通过 npx 运行。

方式一：直接使用 npx（推荐）

npx openskills --version

方式二：全局安装（可选）

npm install -g openskills

资料来源：README.md:1-5

安装技能包

从 Anthropic 市场安装

npx openskills install anthropics/skills

资料来源：README.md:12-15

从 GitHub 仓库安装

npx openskills install your-org/your-skills

资料来源：README.md:17-19

从本地路径安装

npx openskills install ./local-skills/my-skill

支持绝对路径、相对路径和波浪号展开路径。

资料来源：CHANGELOG.md:25-30

从私有仓库安装

npx openskills install [email protected]:your-org/private-skills.git

OpenSkills 自动使用系统 SSH 密钥进行身份验证。

资料来源：CHANGELOG.md:31-35

安装选项说明

资料来源：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 文件。

基本同步流程

npx openskills sync

同步过程会：

1. 扫描已安装的技能目录
2. 读取每个技能的 SKILL.md 元数据
3. 生成 <available_skills> XML 块
4. 更新目标 AGENTS.md 文件

资料来源：src/commands/sync.ts:1-15

生成的文件格式

同步后的 AGENTS.md 包含以下结构：

<skills_system priority="1">
<available_skills>
<skill>
<name>skill-name</name>
<description>技能描述</description>
<location>project</location>
</skill>
</available_skills>
</skills_system>

资料来源：src/utils/agents-md.ts:45-60

使用技能

查看已安装的技能

npx openskills list

资料来源：README.md:57-60

读取技能内容

npx openskills read <skill-name>

例如读取 PDF 技能：

npx openskills read pdf

资料来源：README.md:1-7

加载多个技能

npx openskills read skill-one,skill-two

资料来源：README.md:1-7

工作流程图

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[执行技能指令]

常用命令速查表

资料来源：README.md:57-60

本地技能开发

创建最小技能结构

my-skill/
└── SKILL.md

带资源的技能结构

my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

资料来源：README.md:85-95

使用符号链接进行开发

git clone [email protected]: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 正文：

概述

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 │ ...               │
└─────────────────────────────────────────────────────────────┘

核心依赖

资料来源：package.json:1-25

命令模块设计

命令注册机制

CLI 采用 Commander.js 框架进行命令注册和参数解析。主入口文件 src/cli.ts 负责定义所有可用命令：

program
  .command('list')
  .description('List all installed skills')
  .action(listSkills);

program
  .command('install <source>')
  .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

支持的命令列表

数据模型

技能元数据结构

interface Skill {
  name: string;          // 技能标识符（连字符格式）
  description: string;   // 技能描述（1-2句）
  location: 'project' | 'global' | 'plugin';
}

资料来源：src/types.ts

技能来源元数据

interface SkillSourceMetadata {
  source: string;           // 原始安装来源
  sourceType: 'git' | 'local';
  repoUrl?: string;         // Git 仓库 URL
  subpath?: string;         // 子目录路径
  localPath?: string;       // 本地路径
  installedAt: string;      // ISO 时间戳
}

资料来源：src/commands/install.ts:80-100

技能安装流程

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[安装完成]

安装元数据构建逻辑

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：

export function generateSkillsXml(skills: Skill[]): string {
  const skillTags = skills
    .map((s) => `<skill>
<name>${s.name}</name>
<description>${s.description}</description>
<location>${s.location}</location>
</skill>`)
    .join('\n\n');
  // 返回完整的 skills_system XML 块
}

资料来源：src/utils/agents-md.ts:60-80

AGENTS.md 模板结构

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
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 <skill-name>` (run in your shell)
- Only use skills listed in <available_skills>
</usage>

<available_skills>

${skillTags}

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

资料来源：src/utils/agents-md.ts:1-30

内容替换策略

graph LR
    A[读取 AGENTS.md] --> B{检测标记类型}
    B -->|XML 标记| C[使用正则替换 skills_system 块]
    B -->|HTML 注释| D[使用正则替换 TABLE 块]
    C --> E[写入更新后的内容]
    D --> E

替换逻辑支持两种标记格式以保证向后兼容：

• XML 格式：<skills_system>...</skills_system>
• HTML 注释格式：<!-- SKILLS_TABLE_START -->...<!-- SKILLS_TABLE_END -->

资料来源：src/utils/agents-md.ts:40-55

技能更新机制

更新流程

graph TD
    A[update 命令] --> B[读取技能元数据]
    B --> C{判断来源类型}
    C -->|local| D[验证本地路径存在]
    C -->|git| E[克隆最新仓库]
    D -->|路径缺失| F[跳过并警告]
    D -->|路径有效| G[复制文件到安装目录]
    E --> G
    G --> H[更新 installedAt 时间戳]
    H --> I[更新完成]

本地源处理

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

技能目录结构

安装优先级

系统支持多层级的技能安装目录，按优先级从高到低排列：

安装时使用 --universal 标志会将技能安装到 .agent/skills/，适用于同时使用 Claude Code 和其他代理（如 Cursor、Windsurf、Aider）的场景。

资料来源：README.md 和 src/cli.ts

技能包标准结构

skill-name/
├── SKILL.md              # 必需：技能定义文件
├── references/           # 可选：参考文档（API 文档、详细指南）
├── scripts/              # 可选：可执行脚本（Python/Bash）
└── assets/               # 可选：静态资源（模板、图片）

错误处理机制

// 错误处理流程
if (err.code === 'commander.unknownOption' || err.code === 'commander.invalidArgument') {
  // 参数错误：Commander 已显示错误信息
  process.exit(1);
}
// 其他错误
process.exit(err.exitCode || 1);

资料来源：src/cli.ts:10-20

冲突检测

安装前会检查目标路径是否已存在技能：

async function warnIfConflict(
  skillName: string, 
  targetPath: string, 
  isProject: boolean, 
  skipPrompt = false
): Promise<boolean> {
  if (existsSync(targetPath)) {
    if (skipPrompt) {
      // 自动覆盖模式
    }
    // 交互式确认模式
  }
  return true;
}

资料来源：src/commands/install.ts:95-110

SKILL.md 格式规范

YAML 前置元数据

每个技能必须以 YAML frontmatter 开头：

概述

OpenSkills CLI 提供了一套完整的命令，用于管理 AI 代理技能的生命周期。CLI 基于 Node.js 构建，使用 Commander.js 作为命令行参数解析框架，并集成了 Inquirer.js 用于交互式提示。 资料来源：src/cli.ts:1-50

核心功能模块

命令详解

install - 安装技能

install 命令用于从多种来源安装 AI 技能到本地环境。

#### 基本语法

npx openskills install <source> [options]

#### 参数与选项

#### 安装来源类型

``bash npx openskills install anthropics/skills ``

1. Anthropic Marketplace

``bash npx openskills install your-org/your-skills ``

1. 任意 GitHub 仓库

``bash npx openskills install ./local-skills/my-skill ``

1. 本地路径

``bash npx openskills install [email protected]:your-org/private-skills.git ``

1. 私有 Git 仓库

#### 安装行为流程

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[安装完成]

#### 元数据构建

安装过程中，系统会根据来源类型构建不同的元数据：

资料来源：src/commands/install.ts:1-80

概述

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

功能概述

sync 命令的主要职责是根据已安装技能的元数据，动态生成符合 Anthropic Agent Skills 规范的 XML 内容，并将其注入到 AGENTS.md 文件中。生成的 XML 遵循特定的优先级机制，支持渐进式加载（Progressive Disclosure）模式。

核心功能：

资料来源：src/cli.ts:35-38

命令行接口

基本语法

npx openskills sync [选项]

参数与选项

使用示例：

# 默认同步到 AGENTS.md
npx openskills sync

# 跳过交互确认
npx openskills sync -y

# 输出到自定义路径
npx openskills sync -o .ruler/AGENTS.md

资料来源：src/cli.ts:42-45

工作流程

sync 命令的执行流程可分为三个主要阶段：

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 结构如下：

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
当用户请求任务时，检查以下可用技能...
</usage>

<available_skills>
<skill>
<name>skill-name</name>
<description>技能描述</description>
<location>project</location>
</skill>
</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

资料来源：src/utils/agents-md.ts:55-85

阶段三：文件更新

sync 命令使用 replaceSkillsSection 函数处理目标文件。该函数支持两种标记格式：

``html <skills_system>...</skills_system> ``

1. XML 标记格式（首选）：

``html <!-- SKILLS_TABLE_START -->...<!-- SKILLS_TABLE_END --> ``

1. HTML 注释格式（向后兼容）：

函数会自动检测文件中存在的标记格式，并执行相应的替换操作。

资料来源：src/utils/agents-md.ts:88-110

核心实现

agents-md.ts 工具模块

该模块提供了三个核心函数：

#### parseCurrentSkills(content: string): string[]

解析 AGENTS.md 文件中当前已列出的技能名称：

const skillRegex = /<skill>[\s\S]*?<name>([^<]+)<\/name>[\s\S]*?<\/skill>/g;

正则表达式匹配 <skill> 标签块，提取其中的 <name> 元素值。

资料来源：src/utils/agents-md.ts:113-122

#### generateSkillsXml(skills: Skill[]): string

根据技能数组生成完整的 XML 区块：

export function generateSkillsXml(skills: Skill[]): string {
  const skillTags = skills
    .map(
      (s) => `<skill>
<name>${s.name}</name>
<description>${s.description}</description>
<location>${s.location}</location>
</skill>`
    )
    .join('\n\n');
  // ... 生成完整 XML 结构
}

每个技能生成独立的 <skill> 标签块，包含三个子元素：

• <name>：技能标识符
• <description>：技能描述
• <location>：安装位置（project 或 global）

资料来源：src/utils/agents-md.ts:125-148

#### replaceSkillsSection(content: string, newSection: string): string

执行实际的文件替换操作：

export function replaceSkillsSection(content: string, newSection: string): string {
  const startMarker = '<skills_system';
  const endMarker = '</skills_system>';

  if (content.includes(startMarker)) {
    const regex = /<skills_system[^>]*>[\s\S]*?<\/skills_system>/;
    return content.replace(regex, newSection);
  }
  // ... 处理 HTML 注释格式
}

函数首先尝试使用 XML 标记进行匹配和替换，如果失败则回退到 HTML 注释格式。

资料来源：src/utils/agents-md.ts:88-110

Skill 数据模型

interface Skill {
  name: string;        // 技能标识符
  description: string; // 技能描述
  location: string;    // 安装位置：'project' | 'global'
}

资料来源：src/types.ts

与 update 命令的协同

sync 命令与 update 命令存在密切配合关系。当用户执行 npx openskills update 时，更新后的技能元数据会被重新写入，此时可以使用 sync 命令将更新后的技能信息同步到 AGENTS.md：

# 更新所有技能后同步
npx openskills update
npx openskills sync

update 命令支持更新本地路径安装的技能：

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 命令生成的文件采用固定的模板结构，包含以下部分：

生成的完整结构示例：

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
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 <skill-name>` (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 <available_skills> below
- Do not invoke a skill that is already loaded in your context
</usage>

<available_skills>
<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit...</description>
<location>project</location>
</skill>
</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

资料来源：src/utils/agents-md.ts:55-85

配置选项详解

输出路径配置

sync 命令支持通过 -o 或 --output 选项指定输出文件路径：

特殊功能：

• 自动创建目录：如果指定的输出路径包含不存在的目录，系统会自动创建
• 自动创建文件：如果目标文件不存在，系统会创建文件并添加标题
• 自动创建区块：如果文件中不存在 <skills_system> 区块，系统会自动插入

资料来源：src/cli.ts:42-45

非交互模式

使用 -y 或 --yes 标志可以跳过所有交互式确认，直接同步所有已安装的技能：

# CI/CD 环境推荐用法
npx openskills sync -y

此模式适用于自动化脚本和持续集成环境。

最佳实践

1. 定期同步

建议在以下时机执行 sync 命令：

2. 多代理环境配置

在同时使用 Claude Code 和其他 Agent（如 Cursor、Windsurf）的环境中，推荐使用 --universal 标志安装技能到 .agent/skills/ 目录：

npx openskills install your-org/your-skills --universal
npx openskills sync -o .agent/AGENTS.md

这样可以避免与 Claude Code 原生插件市场的冲突。

3. 版本控制建议

将 AGENTS.md 纳入版本控制，确保团队成员获得一致的技能配置。

错误处理

sync 命令可能遇到的错误场景及处理方式：

相关命令

总结

sync 命令是 OpenSkills 生态系统的关键连接点，它将本地安装的技能与 AI Agent 的上下文系统桥接起来。通过解析已安装技能的元数据并生成符合规范的 XML 内容，该命令使得 AI Agent 能够在需要时动态加载相应的技能指导。

核心要点：

• 使用 -o 选项支持灵活的输出路径配置
• -y 标志实现完全非交互式同步
• 支持 XML 和 HTML 注释两种标记格式
• 自动处理文件创建和目录结构

概述

update 命令是 OpenSkills 提供的核心功能之一，用于从已记录的源代码刷新已安装的技能（Skills）。该命令在 v1.5.0 版本中引入，解决了用户安装技能后如何获取更新的问题。

核心功能

• 从 Git 仓库更新技能
• 从本地目录更新技能
• 批量更新所有已安装的技能
• 跳过无法确定源代码的技能并给出提示

资料来源：CHANGELOG.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

目录职责

资料来源：examples/my-first-skill/references/skill-format.md:45-60

YAML前端块规范

每个SKILL.md文件必须以YAML前端块开始，该块用于定义技能的基本元数据。

必需字段

目录结构

OpenSkills 采用分层目录结构存储技能数据，支持项目级别和全局级别的安装。

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]

目录层级与优先级

资料来源：src/utils/dirs.ts

目录路径解析

// 技能目录名称常量
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 文件，用于记录技能的来源和安装信息。

元数据结构

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

元数据写入

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

技能发现机制

技能发现是定位系统中所有已安装技能的核心功能。

技能发现流程

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[返回技能列表]

技能查找实现

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

技能目录遍历

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 在本地开发工作流中支持符号链接。被破坏的符号链接会被优雅地跳过，不会导致错误：

// 跳过断裂的符号链接
if (lstatSync(skillPath).isSymbolicLink() && !existsSync(skillPath)) {
  continue;
}

资料来源：src/utils/skills.ts:50-52

技能信息解析

SKILL.md 文件解析

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 解析

function parseFrontmatter(yaml: string): Record<string, string> {
  const result: Record<string, string> = {};
  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 命令负责维护其中的技能列表。

同步数据流

graph LR
    A[技能目录] --> B[findAllSkills]
    B --> C[Skill 对象数组]
    C --> D[generateSkillsXml]
    D --> E[<available_skills> XML]
    E --> F[replaceSkillsSection]
    F --> G[AGENTS.md 文件]

技能 XML 生成

export function generateSkillsXml(skills: Skill[]): string {
  const skillTags = skills
    .map(
      (s) => `<skill>
<name>${s.name}</name>
<description>${s.description}</description>
<location>${s.location}</location>
</skill>`
    )
    .join('\n\n');
  
  // 完整的 skills_system XML 结构
  return `<skills_system priority="1">
...
<available_skills>

${skillTags}

</available_skills>
</skills_system>`;
}

资料来源：src/utils/agents-md.ts:50-80

当前技能解析

export function parseCurrentSkills(content: string): string[] {
  const skillNames: string[] = [];
  const skillRegex = /<skill>[\s\S]*?<name>([^<]+)<\/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 命令支持交互式选择界面：

// 排序：项目级别优先
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 仓库安装的技能存储以下信息：

资料来源：src/commands/install.ts:80-95

本地来源

从本地路径安装的技能存储以下信息：

资料来源：src/commands/install.ts:97-107

元数据构建

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

技能更新机制

更新功能利用存储的元数据重新拉取技能：

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

本地技能更新

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 技能更新

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 接口

interface Skill {
  name: string;              // 技能名称（必需）
  description: string;      // 技能描述（必需）
  path: string;             // 技能文件系统路径
  location: 'project' | 'global';  // 安装位置
}

InstallSourceInfo 接口

interface InstallSourceInfo {
  source: string;
  sourceType: 'git' | 'local';
  repoUrl?: string;
  localPath?: string;
  isUrl: boolean;
  skillName: string;
  skillDir: string;
}

AGENTS.md 输出结构

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.
...
</usage>

<available_skills>
<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit...</description>
<location>project</location>
</skill>
</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

资料来源：src/utils/agents-md.ts:1-50

文件清单

最佳实践

1. 项目级别优先：默认使用项目级别安装，便于版本控制和团队协作
2. 元数据完整性：安装后检查 metadata.json 确保信息正确
3. 符号链接开发：本地开发时使用符号链接避免重复复制
4. 定期同步：更新技能后执行 npx openskills sync 保持 AGENTS.md 最新
5. 冲突预防：使用 --universal 参数避免与 Claude Code 插件市场冲突

项目概述

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

开发环境配置

环境要求

资料来源：package.json:23

安装步骤

# 克隆项目
git clone https://github.com/numman-ali/openskills.git
cd openskills

# 安装依赖
npm install

本地链接与测试

开发过程中可以使用 npm link 将本地包链接到全局，使 CLI 命令在本地可用：

npm link

链接后即可在任意目录下使用 openskills 命令：

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

核心模块职责

资料来源：CONTRIBUTING.md:18-24

开发命令

运行测试

# 运行所有测试
npm run test

# 监听模式（文件变化自动重跑）
npm run test:watch

# 生成覆盖率报告
npm run test:coverage

OpenSkills 使用 Vitest 作为测试框架，测试文件位于 tests/utils/ 目录。测试覆盖包括符号链接检测、YAML 解析、install 命令集成测试、sync 命令集成测试以及完整的 E2E CLI 工作流测试。

资料来源：CONTRIBUTING.md:4-6

构建项目

npm run build

构建输出通过 tsup 处理，将 TypeScript 编译为 JavaScript 并生成类型声明文件。

代码检查与格式化

项目使用 TypeScript 编译器进行类型检查：

npm run lint    # 代码风格检查
npm run format  # 代码格式化

CLI 命令参考

主要命令列表

资料来源：src/cli.ts:19-46

安装命令详解

# 从 GitHub 安装
npx openskills install anthropics/skills

# 从本地路径安装
npx openskills install ./local-skills/my-skill

# 从私有仓库安装
npx openskills install [email protected]: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

同步命令详解

# 同步到默认 AGENTS.md
npx openskills sync

# 指定输出文件
npx openskills sync -o .ruler/AGENTS.md

# 非交互模式
npx openskills sync --yes

sync 命令会扫描已安装技能的 SKILL.md 文件，提取 name、description、location 等元数据，生成符合 Anthropic 规范的 <available_skills> XML 区块并写入目标文件。

资料来源：src/utils/agents-md.ts:45-70

代码提交规范

提交信息格式

<类型>: <简短描述>

[可选的详细说明]

提交类型

提交前检查清单

• [ ] 所有测试通过 npm run test
• [ ] 代码符合 TypeScript 类型检查
• [ ] 新功能包含相应的测试用例
• [ ] 更新了相关文档（如有 API 变更）

问题报告指南

报告问题时，请确保包含以下信息：

资料来源：CONTRIBUTING.md:26-32

许可协议

通过向 OpenSkills 项目提交贡献，您同意您的贡献将按照 Apache 2.0 许可证授权。贡献者无需签署任何额外的贡献者许可协议。

资料来源：CONTRIBUTING.md:34

技能开发指南

OpenSkills 兼容 Anthropic 的 SKILL.md 格式。开发新技能时，需要遵循以下结构：

my-skill/
├── SKILL.md              # 主技能文件（必需）
├── references/           # 参考文档目录
├── scripts/              # 可执行脚本目录
└── assets/               # 静态资源目录

SKILL.md 格式要求

Pitfall Log / 踩坑日志

项目：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