openskills 版本演进全解:从 CHANGELOG 追溯 v1.0.0 至 v1.5.0 的功能、安全与 CLI 实现细节
openskills 版本演进全解:从 CHANGELOG 追溯 v1.0.0 至 v1.5.0 的功能、安全与 CLI 实现细节
openskills 是一个面向 AI 编码代理的通用 skills 加载器,其 CHANGELOG.md 完整记录了项目从 v1.0.0(2025-10-26)到 v1.5.0(2026-01-17)共 9 个版本的演进轨迹。本文以该变更记录为主体,逐版本还原每个新增能力、行为变更与安全修复的设计意图,并结合当前仓库源码(src/cli.ts、src/commands/update.ts 等)印证这些条目背后的真实实现,帮助你不仅知道"改了什么",还理解"为什么这么改、现在该如何用"。
一、变更记录的格式与版本约定
CHANGELOG.md 开篇声明了两条约定:
- 格式基于 Keep a Changelog(每个版本分为 Added / Changed / Fixed / Security 等分类);
- 版本号遵循 Semantic Versioning(语义化版本)规范。
当前仓库中 package.json 声明的版本为 1.5.0,与 CHANGELOG 的最新条目一致,说明本仓库快照即 v1.5.0 代码。这意味着以下所有源码分析都对应 changelog 的最终状态。
二、v1.0.0(2025-10-26):初始发布与核心命令集
CHANGELOG 记录 v1.0.0 是 Initial release,一次性确立了项目的全部核心命令与核心特性:
npx openskills install <source> # Install skills from GitHub repos
npx openskills sync # Generate <available_skills> XML for AGENTS.md
npx openskills list # Show installed skills
npx openskills read <name> # Load skill content for agents
npx openskills manage # Interactive skill removal
npx openskills remove <name> # Remove specific skill
以及四项关键特性:
- 交互式 TUI:所有命令均支持交互式选择;
- Anthropic 的 SKILL.md 格式:技能以带 YAML frontmatter 的 Markdown 文件定义;
- Progressive disclosure(渐进式披露):技能按需加载,而非全部塞进上下文;
- Bundled resources 支持:技能可携带
references/、scripts/、assets/子目录。
对照源码可逐条印证。src/cli.ts 使用 commander 注册了 install、read、update、sync、manage、remove(别名 rm)六个子命令,其中 update 是 v1.5.0 之后才出现的,其余均为 v1.0.0 遗产。交互式能力来自 @inquirer/prompts 依赖(见 package.json 的 dependencies),而 read 命令的输出格式(Reading: <name> / Base directory: ... / 内容 / Skill read: <name>)在 src/commands/read.ts 中实现,注释明确写着 "Output in Claude Code format",与 changelog 所述的"与 Claude Code 同格式"一致。
v1.0.0 的 remove 命令实现极为精简,见 src/commands/remove.ts:先通过 findSkill 按目录优先级定位技能,再 rmSync 删除整个技能目录,并回显技能来自 global 还是 project 位置。
三、v1.1.0 → v1.2.1(2025-10-27):--universal 与"项目级默认安装"的转向
v1.1.0:README 重构与 location 标签修复
- Added:单页综合 README(含技术详解)与 Claude Code 的并排对比;
- Fixed:location 标签现在根据实际安装位置正确显示
project或global。
从源码结构看,location 的判定逻辑在 src/utils/skills.ts 的 findAllSkills 中:const isProjectLocal = dir.includes(process.cwd()),即技能目录路径包含当前工作目录就标记为 project,否则为 global。这个标签会直接影响 list 命令的分组展示(src/commands/list.ts 按 project 优先排序并打印 Summary: X project, Y global),也会写入 sync 生成的 XML 的 <location> 字段。
v1.2.0:--universal 标志与默认值变更
CHANGELOG 记录这是安装目标目录的一次重要调整:
- Added:新增
--universal标志,将技能安装到.agent/skills/而非.claude/skills/,面向 Claude Code + Cursor/Windsurf/Aider 的多代理场景,避免与 Claude Code 原生 marketplace 插件冲突; - Changed:项目级安装成为默认行为(此前是全局),技能默认安装到
./.claude/skills/。
对应实现见 src/commands/install.ts:
const folder = options.universal ? '.agent/skills' : '.claude/skills';
const isProject = !options.global; // Default to project unless --global specified
const targetDir = isProject
? join(process.cwd(), folder)
: join(homedir(), folder);
--universal 决定目录名(.agent/skills vs .claude/skills),而"项目级默认"由 !options.global 体现——不传 --global 就装到 process.cwd() 下。目录解析的单一事实来源在 src/utils/dirs.ts,其 getSearchDirs 定义的搜索优先级为:
./.agent/skills/(项目 universal)~/.agent/skills/(全局 universal)./.claude/skills/(项目)~/.claude/skills/(全局)
这一优先级决定了 list、read、sync 在多个位置存在同名技能时的取舍(src/utils/skills.ts 用 seen 集合按此顺序去重)。
v1.2.1:文档修复
仅一条 Fixed:清理 README 中重复的章节和不正确的 flag 说明——属于文档层修正,不涉及代码行为。
四、v1.3.0(2025-12-14):功能大版本——符号链接、可配置输出、本地/私有源与安全加固
这是 CHANGELOG 中条目最多的一个版本,涵盖四类能力扩展、两项行为变更与三项安全修复。
4.1 符号链接支持(Symlink support)
- 技能目录现在可以是符号链接,指向
git clone下来的技能仓库即可实现"git 更新即技能更新",也支持本地技能开发工作流; - 失效的符号链接(broken symlink)会被优雅跳过而非报错。
实现在 src/utils/skills.ts 的 isDirectoryOrSymlinkToDirectory:
if (entry.isSymbolicLink()) {
try {
const stats = statSync(fullPath); // statSync follows symlinks
return stats.isDirectory();
} catch {
// Broken symlink or permission error
return false;
}
}
statSync 会跟随链接解析目标,解析失败(链接指向不存在的路径)时返回 false,该条目即被跳过——与 changelog 描述的 "Broken symlinks are gracefully skipped" 完全对应。相关测试用例位于 tests/utils/skills.test.ts。
4.2 sync 命令的可配置输出路径(--output / -o)
- 可将技能清单同步到任意
.md文件(例如.ruler/AGENTS.md),不再局限于AGENTS.md; - 目标文件不存在时自动创建,并写入一个以文件名派生的标题(heading);
- 自动创建所需的嵌套目录。
三项行为都能在 src/commands/sync.ts 中逐一找到:
const outputPath = options.output || 'AGENTS.md';
if (!outputPath.endsWith('.md')) {
console.error(chalk.red('Error: Output file must be a markdown file (.md)'));
process.exit(1);
}
if (!existsSync(outputPath)) {
const dir = dirname(outputPath);
if (dir && dir !== '.' && !existsSync(dir)) {
mkdirSync(dir, { recursive: true }); // 自动创建嵌套目录
}
writeFileSync(outputPath, `# ${outputName.replace('.md', '')}\n\n`); // 自动创建带标题的文件
}
注意源码中比 changelog 多出一条约束:输出文件必须是 .md 扩展名,否则直接退出——这是文档未展开的实操细节。写入目标文件的具体内容生成与区段替换逻辑(<skills_system> XML 与 <!-- SKILLS_TABLE_START --> 标记的双轨替换)在 src/utils/agents-md.ts 中实现,并有专门的单测覆盖(tests/commands/sync.test.ts 验证了 <usage> 说明、<location> 标签与空技能列表等场景)。
4.3 本地路径安装(Local path installation)
- 支持绝对路径(
/path/to/skill)、相对路径(./skill、../skill)与波浪号展开(~/my-skills/skill)。
src/commands/install.ts 中的判定与展开逻辑:
function isLocalPath(source: string): boolean {
return (
source.startsWith('/') ||
source.startsWith('./') ||
source.startsWith('../') ||
source.startsWith('~/')
);
}
function expandPath(source: string): string {
if (source.startsWith('~/')) {
return join(homedir(), source.slice(2));
}
return resolve(source);
}
本地安装时,若目录内含 SKILL.md 则按单技能处理,否则按"技能集合目录"递归扫描(installFromRepo 复用了同一套扫描逻辑),这也解释了为什么本地多技能目录和 git 仓库的安装流程是统一的。
4.4 私有 git 仓库支持
- 支持 SSH URL(
git@github.com:org/private-skills.git)、带认证的 HTTPS; - 自动使用系统 SSH 密钥。
isGitUrl 识别 git@、git://、http(s):// 前缀或 .git 后缀的完整 URL;克隆命令为 git clone --depth 1(浅克隆,见 src/commands/install.ts 与 src/commands/update.ts),认证完全依赖本机 git 的 SSH key/凭据配置,克隆失败时会提示 "Tip: For private repos, ensure git SSH keys or credentials are configured"。
4.5 全面测试套件
CHANGELOG 记录该版本建立了 "88 tests across 6 test files"(涵盖符号链接检测、YAML 解析的单元测试,install/sync 集成测试,以及完整 CLI 工作流的 E2E 测试)。当前仓库中测试文件已扩展为 9 个:tests/commands/ 下的 install/sync/update 命令测试、tests/integration/e2e.test.ts(直接 node dist/cli.js 跑真实 CLI 流程)以及 tests/utils/ 下的 dirs/skill-metadata/skill-names/skills/yaml 工具层单测。
4.6 Changed:--yes 全面跳过提示
--yes现在跳过所有交互式提示,实现完全非交互模式(CI/CD 场景);- 覆盖已存在技能时不再询问,而是打印
Overwriting: <skill-name>; - 所有命令均可在无头环境运行。
对应 src/commands/install.ts 中的冲突处理:
async function warnIfConflict(..., skipPrompt = false) {
if (existsSync(targetPath)) {
if (skipPrompt) {
console.log(chalk.dim(`Overwriting: ${skillName}`)); // 与 changelog 描述的提示文本一致
return true;
}
const shouldOverwrite = await confirm({ ... });
...
--yes 在 src/cli.ts 中注册于 install 与 sync 两个命令;sync 的非交互路径则跳过 checkbox 选择、直接同步全部技能(src/commands/sync.ts 的 if (!options.yes) 分支)。
CHANGELOG 还提到 CI workflow 调整:build 步骤移到 tests 之前,确保 dist/cli.js 存在以支撑 E2E 测试——这一点可由 tests/integration/e2e.test.ts 中 const cliPath = join(process.cwd(), 'dist', 'cli.js') 得到印证。
4.7 Security:三项安全修复
这是该版本最值得单独展开的条目,每项都有明确落点:
-
路径穿越防护(Path traversal protection):校验安装路径必须落在目标目录内。src/commands/install.ts 与 src/commands/update.ts 中的
isPathInside用resolve+ 目录分隔符前缀判断实现,越界时打印Security error: Installation path outside target directory并终止——这条错误信息后来成为 v1.3.1 Windows 修复的锚点。 -
符号链接解引用(Symlink dereference):
cpSync统一使用dereference: true,拷贝的是链接目标内容而非链接本身,保证安装出的技能是普通文件树。 -
非贪婪 YAML 正则(Non-greedy YAML regex):防止 frontmatter 解析的潜在 ReDoS。看 src/utils/yaml.ts 的现态:
export function extractYamlField(content: string, field: string): string {
const match = content.match(new RegExp(`^${field}:\\s*(.+?)$`, 'm'));
return match ? match[1].trim() : '';
}
(.+?) 的非贪婪量词正是这条安全修复的直接产物,相关边界用例在 tests/utils/yaml.test.ts。
五、v1.3.1 / v1.3.2 / v1.4.0(2026-01-17):跨平台修复与文档收敛
三个小版本同日发布,分别处理修复、文档与措辞:
v1.3.1(Fixed)
- Windows 安装:路径校验在 Windows 上生效。
Security error: Installation path outside target directory是该修复的标志性报错——问题在于 Linux 下isPathInside的分隔符前缀判断在 Windows 上会因分隔符差异误判,修复后的实现使用path.sep拼接(见 src/commands/install.ts:resolvedTargetDir.endsWith(sep) ? ... : resolvedTargetDir + sep); - CLI 版本号:
npx openskills --version从 package.json 读取。src/cli.ts 中createRequire(import.meta.url)加载../package.json的version字段并传给 commander 的.version(); - 仓库根 SKILL.md:根目录直接放
SKILL.md的单技能仓库现在能正确安装。对应 src/commands/install.ts 中installFromRepo开头对join(repoDir, 'SKILL.md')的专门检查:命中后优先从 frontmatter 的name字段取名(extractYamlField(content, 'name')),其次回退到仓库名。
v1.3.2(Changed)
- 文档与
AGENTS.md生成文本统一使用npx openskills前缀展示所有命令示例——这一约定仍保留在 src/utils/agents-md.ts 的<usage>文本中(Invoke: npx openskills read <skill-name>),意味着即便全局安装,给 Agent 看的调用指引也是npx形式,保证零依赖可执行。
v1.4.0(Changed)
- README 澄清"项目级默认安装"并删除冗余的 sync 说明;
- 安装器输出消息明确区分项目级默认与
--global。对应 src/commands/install.ts 中的双提示:
if (isProject) {
console.log(chalk.dim(`Default install is project-local (${projectLocation}). Use --global for ${globalLocation}.`));
} else {
console.log(chalk.dim(`Global install selected (${globalLocation}). Omit --global for ${projectLocation}.`));
}
六、v1.5.0(2026-01-17):openskills update 与来源元数据追踪
最新版本的三条 Added/Changed 记录围绕同一主题:让安装过的技能可以被可靠地刷新。
6.1 来源元数据追踪(Source metadata tracking)
安装时现在会为每个技能记录来源信息,物理落盘为技能目录下的 .openskills.json。定义在 src/utils/skill-metadata.ts:
export const SKILL_METADATA_FILE = '.openskills.json';
export interface SkillSourceMetadata {
source: string; // 用户传入的原始 source
sourceType: 'git' | 'github' | 'local';
repoUrl?: string; // git 来源的克隆地址
subpath?: string; // 技能在仓库内的相对子路径
localPath?: string; // local 来源的本地目录
installedAt: string; // ISO 时间戳
}
写入时机在 src/commands/install.ts 的每条安装路径末尾:cpSync 拷贝完成后立即 writeSkillMetadata(targetPath, ...)。git 来源记录 repoUrl + subpath(subpath 由 relative(repoDir, skillDir) 计算),local 来源记录 localPath。有了这份元数据,update 才知道"去哪取新版本"。
6.2 openskills update 命令
CHANGELOG 记录其为 "Refresh installed skills from their recorded source (default: all)",并在 src/cli.ts 中注册为 update [skill-names...]。完整流程(src/commands/update.ts):
- 解析目标:
normalizeSkillNames处理传入的名称列表;不传参数则默认更新全部已安装技能,传了参数则只更新匹配项,未匹配的打印Skipping missing skills: ...; - 读取元数据:
readSkillMetadata(skill.path)返回null(即没有.openskills.json)时跳过并提示Skipped: <name> (no source metadata; re-install once to enable updates)——这正是 CHANGELOG 中 Fixed 条目 "Update UX - Skips skills without source metadata and lists them for re-install" 的实现,结尾还会汇总打印Missing source metadata (N): ...并给出重装建议; - local 来源分支:检查
localPath存在且含SKILL.md,直接updateSkillFromDir重新拷贝并刷新installedAt; - git 来源分支:在
~/.openskills-temp-<timestamp>临时目录执行git clone --depth 1 --quiet <repoUrl>,按元数据subpath定位技能目录,验证SKILL.md存在后覆盖安装,finally中无条件清理临时目录; - 汇总输出:
Summary: X updated, Y skipped (Z total),并按失败原因分类列出(缺元数据 / local 源丢失 / local 缺 SKILL.md / 缺 repo URL / 仓库中 SKILL.md 缺失 / clone 失败)。
覆盖安装用的 updateSkillFromDir 同样带有 isPathInside 安全校验和 cpSync(..., { recursive: true, dereference: true }),与 v1.3.0 的安全基线保持一致。
测试层面,tests/commands/update.test.ts 用临时目录 + 伪 HOME 验证了两条核心路径:local 来源技能能从记录的源目录刷新(v1 → v2),无元数据的技能被跳过且原文件不被删除——"跳过不破坏"是 update 命令的重要语义保证。
6.3 read 支持逗号分隔的多个技能名
CHANGELOG 记录 "Multi-skill read - openskills read supports comma-separated names"。实现在 src/utils/skill-names.ts:
export function normalizeSkillNames(input: string[] | string | undefined): string[] {
if (!input) return [];
const raw = Array.isArray(input) ? input : [input];
const names = raw.flatMap((name) => name.split(',')); // 逗号拆分
const cleaned = names.map((name) => name.trim()).filter(Boolean);
return Array.from(new Set(cleaned)); // 去重
}
因此 npx openskills read pdf,xlsx 与 npx openskills read pdf xlsx 等价(commander 的 read <skill-names...> 变长参数 + 逗号拆分 + 去重)。src/commands/read.ts 对每个名字逐个 findSkill,任一缺失则整体报错并列出四个搜索目录,全部命中则依次输出每个技能的完整内容,供 Agent 一次拉取多个技能。同一 normalizeSkillNames 也服务于 update 命令,保证两个命令的名称解析行为一致。
6.4 配套改动
- Generated usage text:
sync写入AGENTS.md的<usage>文本澄清了 shell 调用方式("run in your shell"),并补充了多技能用法示例(见 src/utils/agents-md.ts 第 43–44 行); - README:新增 update 使用指引与人类使用提示(对应 README.md 的 "Updating Skills" 与 "Tips" 章节)。
七、版本变更速查表
| 版本 | 日期 | 关键变更 |
|---|---|---|
| 1.0.0 | 2025-10-26 | 初始发布:install / sync / list / read / manage / remove 六命令;SKILL.md 格式、渐进式披露、bundled resources |
| 1.1.0 | 2025-10-27 | 单页 README 与 Claude Code 对比;location 标签正确显示 project/global |
| 1.2.0 | 2025-10-27 | 新增 --universal(安装到 .agent/skills/);项目级安装成为默认 |
| 1.2.1 | 2025-10-27 | README 清理重复章节与错误 flag |
| 1.3.0 | 2025-12-14 | 符号链接支持;sync 的 --output/-o;本地路径安装;私有 git 仓库;88 测试 / 6 测试文件;--yes 全非交互;路径穿越防护、dereference 拷贝、非贪婪 YAML 正则 |
| 1.3.1 | 2026-01-17 | Windows 路径校验修复;--version 读 package.json;仓库根 SKILL.md 可安装 |
| 1.3.2 | 2026-01-17 | 文档与生成文本统一使用 npx openskills 前缀 |
| 1.4.0 | 2026-01-17 | 文档澄清项目级默认;安装提示明确区分 project vs --global |
| 1.5.0 | 2026-01-17 | 新增 openskills update;安装记录 .openskills.json 来源元数据;read 支持逗号分隔多技能;无元数据技能被跳过并列出待重装 |
八、实操要点:这些版本变更意味着什么
结合 changelog 与源码,面向使用者可以归纳出四条可操作的结论:
- 元数据是
update的前提:v1.5.0 之前安装的技能没有.openskills.json,npx openskills update会跳过并在结尾列出它们——重装一次即可补齐元数据。这是 CHANGELOG "Fixed: Update UX" 条目给出的官方迁移路径。 - CI 环境一律加
--yes:自 v1.3.0 起install/sync在-y下完全无提示,覆盖已有技能时打印Overwriting: <name>后继续,适合流水线批量执行。 sync -o让技能清单可以落地到任意 markdown 文件(必须是.md,源码强制校验),例如同步到.ruler/AGENTS.md之类的自定义约定文件,缺失的目录与文件会自动创建。- 符号链接 + 本地源是本地开发技能的推荐姿势:把技能仓库
ln -s进.claude/skills/(或从本地路径安装),源码改动即时生效;update命令的 local 分支也能直接从记录的localPath重新同步。
从源码结构看,整个演进脉络是清晰的:v1.0.0 确立命令面,v1.2.0 修正安装位置的默认语义,v1.3.0 补齐来源多样性(本地/私有/符号链接)与安全基线,v1.3.1–1.4.0 收敛跨平台与文档问题,v1.5.0 通过来源元数据把"安装"升级为"可维护的生命周期"。对维护者与集成方而言,CHANGELOG.md 中每条条目基本都能在 src/ 或 tests/ 中找到对应实现与验证,这也是这份变更记录可读性与可信度兼得的原因。