符号链接支持

学完你能做什么

理解符号链接的核心价值和适用场景
掌握 ln -s 命令创建符号链接
了解 OpenSkills 如何自动处理符号链接
实现基于 git 的技能自动更新
高效进行本地技能开发
处理损坏的符号链接

前置知识

本教程假设你已经了解了安装来源详解和安装第一个技能，理解基本的技能安装流程。

你现在的困境

你可能已经学会了如何安装和更新技能，但是在使用符号链接时面临以下问题：

本地开发更新麻烦：修改技能后需要重新安装或手动复制文件
多项目共享技能困难：同一个技能在多个项目中使用，每次更新都需要同步
版本管理混乱：技能文件分散在不同项目，难以用 git 统一管理
更新流程繁琐：从 git 仓库更新技能需要重新安装整个仓库

其实 OpenSkills 支持符号链接，可以让你通过 symlink 实现基于 git 的技能自动更新和高效的本地开发工作流。

什么时候用这一招

符号链接的适用场景：

场景	是否需要符号链接	示例
本地技能开发	✅ 是	开发自定义技能，频繁修改和测试
多项目共享技能	✅ 是	团队共享技能仓库，多个项目同时使用
基于 git 的自动更新	✅ 是	技能仓库更新后，所有项目自动获得最新版本
一次安装，永久使用	❌ 否	只安装不修改，直接用 `install` 即可
测试第三方技能	❌ 否	临时测试技能，不需要符号链接

推荐做法

本地开发用符号链接：开发自己的技能时，使用 symlink 避免重复复制
团队共享用 git + symlink：团队技能仓库放在 git 中，各项目通过 symlink 共享
生产环境用普通安装：稳定部署时，使用普通 install 安装，避免依赖外部目录

核心思路：链接而非复制

传统安装方式：

┌─────────────────┐
│  Git 仓库       │
│  ~/dev/skills/ │
│  └── my-skill/ │
└────────┬────────┘
         │ 复制
         ▼
┌─────────────────┐
│ .claude/skills/ │
│  └── my-skill/ │
│     └── 完整副本 │
└─────────────────┘

问题：Git 仓库更新后，.claude/skills/ 中的技能不会自动更新。

符号链接方式：

┌─────────────────┐
│  Git 仓库       │
│  ~/dev/skills/ │
│  └── my-skill/ │ ← 真实文件在这里
└────────┬────────┘
         │ 符号链接（ln -s）
         ▼
┌─────────────────┐
│ .claude/skills/ │
│  └── my-skill/ │ → 指向 ~/dev/skills/my-skill
└─────────────────┘

优势：Git 仓库更新后，符号链接指向的内容自动更新，无需重新安装。

重要概念

符号链接（Symlink）：一种特殊的文件类型，它指向另一个文件或目录。OpenSkills 在查找技能时会自动识别符号链接并跟随它们指向的实际内容。损坏的符号链接（指向不存在的目标）会被自动跳过，不会导致崩溃。

源码实现（src/utils/skills.ts:10-25）：

typescript

function isDirectoryOrSymlinkToDirectory(entry: Dirent, parentDir: string): boolean {
  if (entry.isDirectory()) {
    return true;
  }
  if (entry.isSymbolicLink()) {
    try {
      const fullPath = join(parentDir, entry.name);
      const stats = statSync(fullPath); // statSync follows symlinks
      return stats.isDirectory();
    } catch {
      // Broken symlink or permission error
      return false;
    }
  }
  return false;
}

关键点：

entry.isSymbolicLink() 检测符号链接
statSync() 自动跟随符号链接到目标
try/catch 捕获损坏的符号链接，返回 false 跳过

跟我做

第 1 步：创建技能仓库

为什么 先创建一个 git 仓库用于存放技能，模拟团队共享的场景。

打开终端，执行：

bash

# 创建技能仓库目录
mkdir -p ~/dev/my-skills
cd ~/dev/my-skills

# 初始化 git 仓库
git init

# 创建一个示例技能
mkdir -p my-first-skill
cat > my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: A sample skill for demonstrating symlink support
---

# My First Skill

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"
EOF

# 提交到 git
git add .
git commit -m "Initial commit: Add my-first-skill"

你应该看到：成功创建 git 仓库并提交技能。

解释：

技能存放在 ~/dev/my-skills/ 目录
使用 git 版本管理，方便团队协作
这个目录是技能的"真实位置"

第 2 步：创建符号链接

为什么 学习如何使用 ln -s 命令创建符号链接。

继续在项目目录执行：

bash

# 返回项目根目录
cd ~/my-project

# 创建技能目录
mkdir -p .claude/skills

# 创建符号链接
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# 查看符号链接
ls -la .claude/skills/

你应该看到：

.claude/skills/
└── my-first-skill -> /Users/yourname/dev/my-skills/my-first-skill

解释：

ln -s 创建符号链接
-> 后面显示指向的实际路径
符号链接本身只是一个"指针"，不占用实际空间

第 3 步：验证符号链接工作正常

为什么 确认 OpenSkills 能够正确识别和读取符号链接技能。

执行：

bash

# 列出技能
npx openskills list

# 读取技能内容
npx openskills read my-first-skill

你应该看到：

  my-first-skill           (project)
    A sample skill for demonstrating symlink support

Summary: 1 project, 0 global (1 total)

读取技能输出：

markdown

---
name: my-first-skill
description: A sample skill for demonstrating symlink support
---

# My First Skill

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"

解释：

OpenSkills 自动识别符号链接
符号链接技能显示 (project) 标签
读取的内容来自符号链接指向的原始文件

第 4 步：基于 git 的自动更新

为什么 体验符号链接的最大优势：git 仓库更新后，技能自动同步。

在技能仓库中修改技能：

bash

# 进入技能仓库
cd ~/dev/my-skills

# 修改技能内容
cat > my-first-skill/SKILL.md << 'EOF'
---
name: my-first-skill
description: Updated version with new features
---

# My First Skill (Updated)

When user asks for help with this skill, follow these steps:
1. Check the symlink is working
2. Print "Symlink support is working!"
3. NEW: This feature was updated via git!
EOF

# 提交更新
git add .
git commit -m "Update skill: Add new feature"

现在在项目目录验证更新：

bash

# 返回项目目录
cd ~/my-project

# 读取技能（无需重新安装）
npx openskills read my-first-skill

你应该看到：技能内容已自动更新，包含新的功能说明。

解释：

符号链接指向的文件更新后，OpenSkills 自动读取最新内容
无需重新执行 openskills install
实现了"一次更新，多处生效"

第 5 步：多项目共享技能

为什么 体验符号链接在多项目场景下的优势，避免技能重复安装。

创建第二个项目：

bash

# 创建第二个项目
mkdir ~/my-second-project
cd ~/my-second-project

# 创建技能目录和符号链接
mkdir -p .claude/skills
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# 验证技能可用
npx openskills list

你应该看到：

  my-first-skill           (project)
    Updated version with new features

Summary: 1 project, 0 global (1 total)

解释：

多个项目可以创建指向同一个技能的符号链接
技能仓库更新后，所有项目自动获得最新版本
避免了技能重复安装和更新

第 6 步：处理损坏的符号链接

为什么 了解 OpenSkills 如何优雅地处理损坏的符号链接。

模拟损坏的符号链接：

bash

# 删除技能仓库
rm -rf ~/dev/my-skills

# 尝试列出技能
npx openskills list

你应该看到：损坏的符号链接被自动跳过，不会报错。

Summary: 0 project, 0 global (0 total)

解释：

源码中的 try/catch 捕获损坏的符号链接
OpenSkills 会跳过损坏的链接，继续查找其他技能
不会导致 openskills 命令崩溃

检查点 ✅

完成以下检查，确认你掌握了本课内容：

[ ] 理解符号链接的核心价值
[ ] 掌握 ln -s 命令的使用
[ ] 了解符号链接和复制文件的区别
[ ] 能够创建基于 git 的技能仓库
[ ] 能够实现技能的自动更新
[ ] 知道如何在多项目中共享技能
[ ] 理解损坏符号链接的处理机制

踩坑提醒

常见错误 1：符号链接路径错误

错误场景：使用相对路径创建符号链接，移动项目后链接失效。

bash

# ❌ 错误：使用相对路径
cd ~/my-project
ln -s ../dev/my-skills/my-first-skill .claude/skills/my-first-skill

# 移动项目后链接失效
mv ~/my-project ~/new-location/project
npx openskills list  # ❌ 找不到技能

问题：

相对路径依赖于当前工作目录
移动项目后相对路径失效
符号链接指向错误位置

正确做法：

bash

# ✅ 正确：使用绝对路径
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# 移动项目后仍然有效
mv ~/my-project ~/new-location/project
npx openskills list  # ✅ 仍然可以找到技能

常见错误 2：混淆硬链接和符号链接

错误场景：使用硬链接而不是符号链接。

bash

# ❌ 错误：使用硬链接（没有 -s 参数）
ln ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# 硬链接是文件的另一个入口，不是指针
# 无法实现"更新一处，处处生效"

问题：

硬链接是文件的另一个入口名
修改任何一个硬链接，其他硬链接也会更新
但删除源文件后，硬链接仍然存在，造成混乱
无法跨文件系统使用

正确做法：

bash

# ✅ 正确：使用符号链接（带 -s 参数）
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# 符号链接是指针
# 删除源文件后，符号链接会失效（OpenSkills 会跳过）

常见错误 3：符号链接指向错误的位置

错误场景：符号链接指向技能目录的父目录，而不是技能目录本身。

bash

# ❌ 错误：指向父目录
ln -s ~/dev/my-skills .claude/skills/my-skills-link

# OpenSkills 会在 .claude/skills/my-skills-link/ 下查找 SKILL.md
# 但实际 SKILL.md 在 ~/dev/my-skills/my-first-skill/SKILL.md

问题：

OpenSkills 会查找 <link>/SKILL.md
但实际技能在 <link>/my-first-skill/SKILL.md
导致找不到技能文件

正确做法：

bash

# ✅ 正确：直接指向技能目录
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# OpenSkills 会查找 .claude/skills/my-first-skill/SKILL.md
# 符号链接指向的目录中就包含 SKILL.md

常见错误 4：忘记同步 AGENTS.md

错误场景：创建符号链接后忘记同步 AGENTS.md。

bash

# 创建符号链接
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# ❌ 错误：忘记同步 AGENTS.md
# AI 代理无法知道有新技能可用

问题：

符号链接创建了，但 AGENTS.md 未更新
AI 代理不知道有新技能
无法调用新技能

正确做法：

bash

# 创建符号链接
ln -s ~/dev/my-skills/my-first-skill .claude/skills/my-first-skill

# ✅ 正确：同步 AGENTS.md
npx openskills sync

# 现在 AI 代理可以看到新技能

本课小结

核心要点：

符号链接是指针：使用 ln -s 创建，指向真实的文件或目录
自动跟随链接：OpenSkills 使用 statSync() 自动跟随符号链接
损坏链接自动跳过：try/catch 捕获异常，避免崩溃
基于 git 自动更新：Git 仓库更新后，技能自动同步
多项目共享：多个项目可以创建指向同一技能的符号链接

决策流程：

[需要使用技能] → [是否需要频繁修改？]
                         ↓ 是
                 [使用符号链接（本地开发）]
                         ↓ 否
                 [是否多个项目共享？]
                         ↓ 是
                 [使用 git + 符号链接]
                         ↓ 否
                 [使用普通 install]

记忆口诀：

本地开发用 symlink：频繁修改，避免重复复制
团队共享 git 链：一次更新，处处生效
绝对路径保稳定：避免相对路径失效
损坏链接自动跳：OpenSkills 自动处理

下一课预告

下一课我们学习 创建自定义技能。
你会学到：
如何从零开始创建自己的技能
理解 SKILL.md 格式和 YAML frontmatter
如何组织技能目录结构（references/、scripts/、assets/）
如何编写高质量的技能说明

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-24

功能	文件路径	行号
符号链接检测	`src/utils/skills.ts`	10-25
技能查找	`src/utils/skills.ts`	30-64
单个技能查找	`src/utils/skills.ts`	69-84

关键函数：

isDirectoryOrSymlinkToDirectory(entry, parentDir)：判断目录项是真实目录还是指向目录的符号链接
- 使用 entry.isSymbolicLink() 检测符号链接
- 使用 statSync() 自动跟随符号链接到目标
- try/catch 捕获损坏的符号链接，返回 false
findAllSkills()：查找所有已安装的技能
- 遍历 4 个搜索目录
- 调用 isDirectoryOrSymlinkToDirectory 识别符号链接
- 自动跳过损坏的符号链接

业务规则：

符号链接被自动识别为技能目录
损坏的符号链接会被优雅地跳过，不会导致崩溃
符号链接和真实目录的查找优先级相同

15 分钟上手

掌握核心操作

多账号与自定义技能

遇到问题怎么办

遇到问题查这里

了解最新改动

符号链接支持

学完你能做什么

你现在的困境

什么时候用这一招

核心思路：链接而非复制

跟我做

第 1 步：创建技能仓库

第 2 步：创建符号链接

第 3 步：验证符号链接工作正常

第 4 步：基于 git 的自动更新

第 5 步：多项目共享技能

第 6 步：处理损坏的符号链接

检查点 ✅

踩坑提醒

常见错误 1：符号链接路径错误

常见错误 2：混淆硬链接和符号链接

常见错误 3：符号链接指向错误的位置

常见错误 4：忘记同步 AGENTS.md

本课小结

下一课预告

附录：源码参考

符号链接支持 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

核心思路：链接而非复制 ​

跟我做 ​

第 1 步：创建技能仓库 ​

第 2 步：创建符号链接 ​

第 3 步：验证符号链接工作正常 ​

第 4 步：基于 git 的自动更新 ​

第 5 步：多项目共享技能 ​

第 6 步：处理损坏的符号链接 ​

检查点 ✅ ​

踩坑提醒 ​

常见错误 1：符号链接路径错误 ​

常见错误 2：混淆硬链接和符号链接 ​

常见错误 3：符号链接指向错误的位置 ​

常见错误 4：忘记同步 AGENTS.md ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

符号链接支持

学完你能做什么

你现在的困境

什么时候用这一招

核心思路：链接而非复制

跟我做

第 1 步：创建技能仓库

第 2 步：创建符号链接

第 3 步：验证符号链接工作正常

第 4 步：基于 git 的自动更新

第 5 步：多项目共享技能

第 6 步：处理损坏的符号链接

检查点 ✅

踩坑提醒

常见错误 1：符号链接路径错误

常见错误 2：混淆硬链接和符号链接

常见错误 3：符号链接指向错误的位置

常见错误 4：忘记同步 AGENTS.md

本课小结

下一课预告

附录：源码参考