故障排除：解决 OpenSkills 常见问题

学完你能做什么

快速诊断和修复 OpenSkills 使用中的常见问题
理解错误信息背后的原因
掌握排查 Git 克隆、权限、文件格式等问题的技巧
了解何时需要重新安装技能

你现在的困境

使用 OpenSkills 时遇到了报错，不知道怎么办：

Error: No SKILL.md files found in repository

或者 git clone 失败、权限错误、文件格式不正确……这些问题都可能导致技能无法正常使用。

什么时候需要看这篇教程

当你遇到以下情况时：

安装失败：从 GitHub 或本地路径安装时出错
读取失败：openskills read 提示找不到技能
同步失败：openskills sync 提示无技能或文件格式错误
更新失败：openskills update 跳过某些技能
权限错误：提示路径访问受限或安全错误

核心思路

OpenSkills 的错误主要分为 4 类：

错误类型	常见原因	解决思路
Git 相关	网络问题、SSH 配置、仓库不存在	检查网络、配置 Git 凭证、验证仓库地址
文件相关	SKILL.md 缺失、格式错误、路径错误	检查文件存在性、验证 YAML 格式
权限相关	目录权限、路径遍历、符号链接	检查目录权限、验证安装路径
元数据相关	更新时元数据丢失、源路径变化	重新安装技能以恢复元数据

排查技巧：

看错误信息：红色输出通常包含具体原因
看黄色提示：通常是警告和建议，如 Tip: For private repos...
检查目录结构：用 openskills list 查看已安装技能
查看源码位置：错误信息会列出搜索路径（4 个目录）

安装失败

问题 1：Git clone 失败

错误信息：

Failed to clone repository
fatal: repository '...' not found
Tip: For private repos, ensure git SSH keys or credentials are configured

可能原因：

原因	场景
仓库不存在	拼写错误的 owner/repo
私有仓库	未配置 SSH key 或 Git 凭证
网络问题	无法访问 GitHub

解决方法：

验证仓库地址：

bash

# 在浏览器中访问仓库 URL
https://github.com/owner/repo

检查 Git 配置（私有仓库）：

bash

# 检查 SSH 配置
ssh -T [email protected]

# 配置 Git 凭证
git config --global credential.helper store

测试克隆：

bash

git clone https://github.com/owner/repo.git

你应该看到：

问题 2：找不到 SKILL.md

错误信息：

Error: No SKILL.md files found in repository
Error: No valid SKILL.md files found

可能原因：

原因	说明
仓库无 SKILL.md	仓库不是技能仓库
SKILL.md 无 frontmatter	缺少 YAML 元数据
SKILL.md 格式错误	YAML 语法错误

解决方法：

检查仓库结构：

bash

# 查看仓库根目录
ls -la

# 查看是否有 SKILL.md
find . -name "SKILL.md"

验证 SKILL.md 格式：
markdown
```
---
name: 技能名称
description: 技能描述
---

技能内容...
```
必须：
- 开头有 --- 分隔的 YAML frontmatter
- 包含 name 和 description 字段

查看官方示例：

bash

git clone https://github.com/anthropics/skills.git
cd skills
ls -la

你应该看到：

仓库中包含一个或多个 SKILL.md 文件
每个 SKILL.md 开头有 YAML frontmatter

问题 3：路径不存在或不是目录

错误信息：

Error: Path does not exist: /path/to/skill
Error: Path must be a directory

可能原因：

原因	说明
路径拼写错误	输入了错误的路径
路径指向文件	应该是目录而不是文件
路径未展开	使用 `~` 时需要展开

解决方法：

验证路径存在：

bash

# 检查路径
ls -la /path/to/skill

# 检查是否为目录
file /path/to/skill

使用绝对路径：

bash

# 获取绝对路径
realpath /path/to/skill

# 安装时使用绝对路径
openskills install /absolute/path/to/skill

使用相对路径：

bash

# 在项目目录中
openskills install ./skills/my-skill

你应该看到：

问题 4：SKILL.md 无效

错误信息：

Error: Invalid SKILL.md (missing YAML frontmatter)

可能原因：

原因	说明
---	---
缺少必需字段	必须有 `name` 和 `description`
YAML 语法错误	冒号、引号等格式问题

解决方法：

检查 YAML frontmatter：

markdown

---              ← 开始分隔符
name: my-skill   ← 必需
description: 技能描述  ← 必需
---              ← 结束分隔符

使用在线 YAML 验证工具：
- 访问 YAML Lint 或类似工具验证语法

参考官方示例：

bash

openskills install anthropics/skills
cat .claude/skills/*/SKILL.md | head -20

你应该看到：

SKILL.md 开头有正确的 YAML frontmatter
包含 name 和 description 字段

问题 5：路径遍历安全错误

错误信息：

Security error: Installation path outside target directory

可能原因：

原因	说明
技能名称包含 `..`	尝试访问目标目录外的路径
符号链接指向外部	symlink 指向目标目录外
恶意技能	技能试图绕过安全限制

解决方法：

检查技能名称：
- 确保技能名称不包含 ..、/ 等特殊字符

检查符号链接：

bash

# 查看技能目录中的符号链接
find .claude/skills/skill-name -type l

# 查看符号链接目标
ls -la .claude/skills/skill-name

使用安全的技能：
- 仅从可信来源安装技能
- 审查技能代码后再安装

你应该看到：

技能名称只包含字母、数字、连字符
无指向外部的符号链接

读取失败

问题 6：技能未找到

错误信息：

Error: Skill(s) not found: my-skill

Searched:
  .agent/skills/ (project universal)
  ~/.agent/skills/ (global universal)
  .claude/skills/ (project)
  ~/.claude/skills/ (global)

Install skills: npx openskills install owner/repo

可能原因：

原因	说明
技能未安装	该技能没有安装在任意目录中
技能名称拼写错误	名称不匹配
安装在其他位置	技能安装在非标准目录

解决方法：

查看已安装技能：
bash
```
openskills list
```
检查技能名称：
- 对比 openskills list 输出
- 确保名称完全匹配（区分大小写）
安装缺失技能：
bash
```
openskills install owner/repo
```

搜索所有目录：

bash

# 检查 4 个技能目录
ls -la .agent/skills/
ls -la ~/.agent/skills/
ls -la .claude/skills/
ls -la ~/.claude/skills/

你应该看到：

openskills list 显示目标技能
技能存在于 4 个目录之一

问题 7：未提供技能名

错误信息：

Error: No skill names provided

可能原因：

原因	说明
忘记传参	`openskills read` 后没有参数
空字符串	传递了空字符串

解决方法：

提供技能名：

bash

# 单个技能
openskills read my-skill

# 多个技能（逗号分隔）
openskills read skill1,skill2,skill3

先查看可用技能：
bash
```
openskills list
```

你应该看到：

成功读取技能内容到标准输出

同步失败

问题 8：输出文件不是 Markdown

错误信息：

Error: Output file must be a markdown file (.md)

可能原因：

原因	说明
输出文件不是 .md	指定了 .txt、.json 等格式
--output 参数错误	路径不以 .md 结尾

解决方法：

使用 .md 文件：

bash

# 正确
openskills sync -o AGENTS.md
openskills sync -o custom.md

# 错误
openskills sync -o AGENTS.txt
openskills sync -o AGENTS

自定义输出路径：

bash

# 输出到子目录
openskills sync -o .ruler/AGENTS.md
openskills sync -o docs/agents.md

你应该看到：

成功生成 .md 文件
文件包含技能 XML 部分

问题 9：无技能安装

错误信息：

No skills installed. Install skills first:
  npx openskills install anthropics/skills --project

可能原因：

原因	说明
从未安装技能	首次使用 OpenSkills
删除了技能目录	手动删除了技能文件

解决方法：

安装技能：

bash

# 安装官方技能
openskills install anthropics/skills

# 从其他仓库安装
openskills install owner/repo

验证安装：
bash
```
openskills list
```

你应该看到：

openskills list 显示至少一个技能
同步成功

更新失败

问题 10：无源元数据

错误信息：

Skipped: my-skill (no source metadata; re-install once to enable updates)

可能原因：

原因	说明
旧版本安装	技能安装于元数据功能之前
手动复制	直接复制技能目录，未通过 OpenSkills 安装
元数据文件损坏	`.openskills.json` 损坏或丢失

解决方法：

重新安装技能：

bash

# 删除旧技能
openskills remove my-skill

# 重新安装
openskills install owner/repo

检查元数据文件：

bash

# 查看技能元数据
cat .claude/skills/my-skill/.openskills.json

保留技能但添加元数据：
- 手动创建 .openskills.json（不推荐）
- 重新安装更简单可靠

你应该看到：

更新成功，无跳过警告

问题 11：本地源缺失

错误信息：

Skipped: my-skill (local source missing)

可能原因：

原因	说明
本地路径被移动	源目录位置改变
本地路径被删除	源目录不存在
路径未展开	使用 `~` 但元数据中存储了展开路径

解决方法：

检查元数据中的本地路径：

bash

cat .claude/skills/my-skill/.openskills.json

恢复源目录或更新元数据：

bash

# 如果源目录移动了
openskills remove my-skill
openskills install /new/path/to/skill

# 或者手动编辑元数据（不推荐）
vi .claude/skills/my-skill/.openskills.json

你应该看到：

本地源路径存在且包含 SKILL.md

问题 12：仓库中找不到 SKILL.md

错误信息：

SKILL.md missing for my-skill
Skipped: my-skill (SKILL.md not found in repo at subpath)

可能原因：

原因	说明
仓库结构变化	技能子路径或名称改变
技能被删除	仓库中不再包含该技能
子路径错误	元数据中记录的子路径不正确

解决方法：

访问仓库查看结构：

bash

# 克隆仓库查看
git clone https://github.com/owner/repo.git
cd repo
ls -la
find . -name "SKILL.md"

重新安装技能：

bash

openskills remove my-skill
openskills install owner/repo/subpath

检查仓库更新历史：
- 在 GitHub 上查看仓库的 commit 历史
- 查找技能移动或删除的记录

你应该看到：

更新成功
SKILL.md 存在于记录的子路径中

权限问题

问题 13：目录权限受限

现象：

操作	现象
安装失败	提示权限错误
删除失败	提示无法删除文件
读取失败	提示文件访问受限

可能原因：

原因	说明
目录权限不足	用户无写入权限
文件权限不足	文件只读
系统保护	macOS SIP、Windows UAC 限制

解决方法：

检查目录权限：

bash

# 查看权限
ls -la .claude/skills/

# 修改权限（谨慎使用）
chmod -R 755 .claude/skills/

使用 sudo（不推荐）：

bash

# 最后的手段
sudo openskills install owner/repo

检查系统保护：

bash

# macOS：检查 SIP 状态
csrutil status

# 如需禁用 SIP（需要恢复模式）
# 不推荐，仅在必要时使用

你应该看到：

符号链接问题

问题 14：符号链接损坏

现象：

现象	说明
列表时跳过技能	`openskills list` 不显示该技能
读取失败	提示文件不存在
更新失败	源路径无效

可能原因：

原因	说明
目标目录被删除	符号链接指向不存在的路径
符号链接损坏	链接文件本身损坏
跨设备链接	某些系统不支持跨设备的符号链接

解决方法：

检查符号链接：

bash

# 查找所有符号链接
find .claude/skills -type l

# 查看链接目标
ls -la .claude/skills/my-skill

# 测试链接
readlink .claude/skills/my-skill

删除损坏的符号链接：
bash
```
openskills remove my-skill
```
重新安装：
bash
```
openskills install owner/repo
```

你应该看到：

无损坏的符号链接
技能正常显示和读取

踩坑提醒

常见错误操作

❌ 不要这样做：

直接复制技能目录 → 会导致元数据缺失，更新失败
手动编辑 .openskills.json → 容易破坏格式，导致更新失败
使用 sudo 安装技能 → 会创建 root 拥有的文件，后续操作可能需要 sudo
删除 .openskills.json → 会导致更新时跳过该技能

✅ 应该这样做：

通过 openskills install 安装 → 自动创建元数据
通过 openskills remove 删除 → 正确清理文件
通过 openskills update 更新 → 自动从源刷新
通过 openskills list 检查 → 确认技能状态

排查技巧

从简单开始：先运行 openskills list 确认状态
看完整错误信息：黄色提示通常包含解决建议
检查目录结构：用 ls -la 查看文件和权限
验证源码位置：错误信息会列出 4 个搜索目录
使用 -y 跳过交互：在 CI/CD 或脚本中使用 -y 标志

本课小结

本课学习了 OpenSkills 常见问题的排查和修复方法：

问题类型	关键解决方法
Git clone 失败	检查网络、配置凭证、验证仓库地址
找不到 SKILL.md	检查仓库结构、验证 YAML 格式
读取失败	用 `openskills list` 检查技能状态
更新失败	重新安装技能恢复元数据
权限问题	检查目录权限、避免使用 sudo

记住：

错误信息通常包含明确的提示
重新安装是解决元数据问题的最简单方法
只从可信来源安装技能

下一步

查看常见问题 (FAQ) → 更多疑问的解答
学习最佳实践 → 避免常见错误
探索安全说明 → 了解安全机制

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-24

功能	文件路径	行号
Git clone 失败处理	`src/commands/install.ts`	162-168
路径不存在错误	`src/commands/install.ts`	205-207
不是目录错误	`src/commands/install.ts`	210-213
SKILL.md 无效	`src/commands/install.ts`	241-243
路径遍历安全错误	`src/commands/install.ts`	256-259
找不到 SKILL.md	`src/commands/install.ts`	378-380
未提供技能名	`src/commands/read.ts`	10-12
技能未找到	`src/commands/read.ts`	26-34
输出文件不是 Markdown	`src/commands/sync.ts`	23-25
无技能安装	`src/commands/sync.ts`	40-43
无源元数据跳过	`src/commands/update.ts`	57-61
本地源缺失	`src/commands/update.ts`	66-71
仓库中找不到 SKILL.md	`src/commands/update.ts`	102-107

关键函数：

hasValidFrontmatter(content): 验证 SKILL.md 是否有有效的 YAML frontmatter
isPathInside(targetPath, targetDir): 验证路径是否在目标目录内（安全检查）
findSkill(name): 按优先级在 4 个目录中查找技能
readSkillMetadata(path): 读取技能的安装源元数据

关键常量：

搜索目录顺序（src/utils/skills.ts）：
1. .agent/skills/ (project universal)
2. ~/.agent/skills/ (global universal)
3. .claude/skills/ (project)
4. ~/.claude/skills/ (global)

15 分钟上手

掌握核心操作

多账号与自定义技能

遇到问题怎么办

遇到问题查这里

了解最新改动

故障排除：解决 OpenSkills 常见问题

学完你能做什么

你现在的困境

什么时候需要看这篇教程

核心思路

安装失败

问题 1：Git clone 失败

问题 2：找不到 SKILL.md

问题 3：路径不存在或不是目录

问题 4：SKILL.md 无效

问题 5：路径遍历安全错误

读取失败

问题 6：技能未找到

问题 7：未提供技能名

同步失败

问题 8：输出文件不是 Markdown

问题 9：无技能安装

更新失败

问题 10：无源元数据

问题 11：本地源缺失

问题 12：仓库中找不到 SKILL.md

权限问题

问题 13：目录权限受限

符号链接问题

问题 14：符号链接损坏

踩坑提醒

本课小结

下一步

附录：源码参考

故障排除：解决 OpenSkills 常见问题 ​

学完你能做什么 ​

你现在的困境 ​

什么时候需要看这篇教程 ​

核心思路 ​

安装失败 ​

问题 1：Git clone 失败 ​

问题 2：找不到 SKILL.md ​

问题 3：路径不存在或不是目录 ​

问题 4：SKILL.md 无效 ​

问题 5：路径遍历安全错误 ​

读取失败 ​

问题 6：技能未找到 ​

问题 7：未提供技能名 ​

同步失败 ​

问题 8：输出文件不是 Markdown ​

问题 9：无技能安装 ​

更新失败 ​

问题 10：无源元数据 ​

问题 11：本地源缺失 ​

问题 12：仓库中找不到 SKILL.md ​

权限问题 ​

问题 13：目录权限受限 ​

符号链接问题 ​

问题 14：符号链接损坏 ​

踩坑提醒 ​

本课小结 ​

下一步 ​

附录：源码参考 ​

故障排除：解决 OpenSkills 常见问题

学完你能做什么

你现在的困境

什么时候需要看这篇教程

核心思路

安装失败

问题 1：Git clone 失败

问题 2：找不到 SKILL.md

问题 3：路径不存在或不是目录

问题 4：SKILL.md 无效

问题 5：路径遍历安全错误

读取失败

问题 6：技能未找到

问题 7：未提供技能名

同步失败

问题 8：输出文件不是 Markdown

问题 9：无技能安装

更新失败

问题 10：无源元数据

问题 11：本地源缺失

问题 12：仓库中找不到 SKILL.md

权限问题

问题 13：目录权限受限

符号链接问题

问题 14：符号链接损坏

踩坑提醒

本课小结

下一步

附录：源码参考