使用技能

学完你能做什么

• 使用 openskills read 命令读取已安装技能的内容
• 理解 AI 代理如何通过该命令加载技能到上下文
• 掌握技能查找的 4 级优先级顺序
• 学会一次读取多个技能（逗号分隔）

前置知识

本教程假设你已经 安装了至少一个技能。如果你还没有安装技能，请先完成技能安装步骤。

---

你现在的困境

你可能已经安装了技能，但是：

• 不知道怎么让 AI 使用技能：技能装好了，但 AI 代理怎么读取？
• 不明白 read 命令的作用：只知道有个 read 命令，但不知道输出是什么
• 不清楚技能查找顺序：全局和项目都有技能，AI 会用哪个？

这些问题其实很常见。让我们一步步来解决。

---

什么时候用这一招

**使用技能（read 命令）**适合这些场景：

• AI 代理需要执行特定任务：如处理 PDF、操作 Git 仓库等
• 验证技能内容是否正确：检查 SKILL.md 的指令是否符合预期
• 了解技能的完整结构：查看技能的 references/、scripts/ 等资源

推荐做法

通常你不会直接使用 read 命令，而是由 AI 代理自动调用。但了解它的输出格式有助于调试和开发自定义技能。

---

🎒 开始前的准备

在开始之前，请确认：

• [ ] 已完成 安装第一个技能
• [ ] 已在项目目录下安装了至少一个技能
• [ ] 可以查看 .claude/skills/ 目录

前置检查

如果还没有安装技能，可以快速安装一个测试技能：

npx openskills install anthropics/skills
# 在交互式界面中选择任意技能（如 pdf）

---

核心思路：按优先级查找并输出技能

OpenSkills 的 read 命令是这样的流程：

[指定技能名] → [按优先级查找] → [找到第一个] → [读取 SKILL.md] → [输出到标准输出]

关键点：

• 4 级查找优先级：

  1. .agent/skills/ (项目 universal)
  2. ~/.agent/skills/ (全局 universal)
  3. .claude/skills/ (项目 claude)
  4. ~/.claude/skills/ (全局 claude)

• 返回第一个匹配：找到第一个就停止，不会查找后续目录

• 输出基础目录：AI 代理需要这个路径来解析技能中的资源文件

---

跟我做

第 1 步：读取单个技能

首先，尝试读取一个已安装的技能。

示例命令：

npx openskills read pdf

为什么

pdf 是我们在上一课安装的技能名称。这个命令会查找并输出该技能的完整内容。

你应该看到：

Reading: pdf
Base directory: /path/to/your/project/.claude/skills/pdf

---
name: pdf
description: Comprehensive PDF manipulation toolkit for extracting text and tables...
...

Skill read: pdf

输出结构解析：

部分	内容	作用
Reading: pdf	技能名称	标识正在读取的技能
Base directory: ...	技能基础目录	AI 用此路径解析 references/、scripts/ 等资源
SKILL.md 内容	完整的技能定义	包含指令、资源引用等
Skill read: pdf	结束标记	标识读取完成

注意

基础目录（Base directory） 非常重要。技能中的 references/some-doc.md 路径会相对于这个目录解析。

---

第 2 步：读取多个技能

OpenSkills 支持一次读取多个技能，技能名用逗号分隔。

示例命令：

npx openskills read pdf,git-workflow

为什么

一次读取多个技能可以减少命令调用次数，提高效率。

你应该看到：

Reading: pdf
Base directory: /path/to/your/project/.claude/skills/pdf

---
name: pdf
description: Comprehensive PDF manipulation toolkit...
...

Skill read: pdf

Reading: git-workflow
Base directory: /path/to/your/project/.claude/skills/git-workflow

---
name: git-workflow
description: Git workflow: Best practices...
...

Skill read: git-workflow

特点：

• 每个技能的输出用空行分隔
• 每个技能都有独立的 Reading: 和 Skill read: 标记
• 技能按命令中指定的顺序读取

进阶用法

技能名可以包含空格，read 命令会自动处理：

npx openskills read pdf, git-workflow  # 空格会被忽略

---

第 3 步：验证技能查找优先级

让我们验证 4 级查找顺序是否正确。

准备环境：

首先，在项目目录和全局目录分别安装技能（使用不同的安装源）：

# 项目本地安装（在当前项目目录）
npx openskills install anthropics/skills

# 全局安装（使用 --global）
npx openskills install anthropics/skills --global

验证优先级：

# 列出所有技能
npx openskills list

你应该看到：

Available skills:

pdf (project)      /path/to/your/project/.claude/skills/pdf
pdf (global)       /home/user/.claude/skills/pdf

Total: 2 skills (1 project, 1 global)

读取技能：

npx openskills read pdf

你应该看到：

Reading: pdf
Base directory: /path/to/your/project/.claude/skills/pdf  ← 优先返回项目技能
...

结论：因为 .claude/skills/ (项目) 的优先级高于 ~/.claude/skills/ (全局)，所以读取到的是项目本地的技能。

实际应用

这个优先级机制让你可以在项目中覆盖全局技能，而不影响其他项目。例如：

• 全局安装常用技能（所有项目共享）
• 项目中安装定制版本（覆盖全局版本）

---

第 4 步：查看技能的完整资源

技能不仅包含 SKILL.md，还可能有 references/、scripts/ 等资源。

查看技能目录结构：

ls -la .claude/skills/pdf/

你应该看到：

.claude/skills/pdf/
├── SKILL.md
├── .openskills.json
├── references/
│   ├── pdf-extraction.md
│   └── table-extraction.md
└── scripts/
    └── extract-pdf.js

读取技能并观察输出：

npx openskills read pdf

你应该看到：

SKILL.md 中包含对资源的引用，如：

## References

See [PDF extraction guide](references/pdf-extraction.md) for details.

## Scripts

Run `node scripts/extract-pdf.js` to extract text from PDF.

关键点

当 AI 代理读取技能时，它会：

1. 获取 Base directory 路径
2. 将 SKILL.md 中的相对路径（如 references/...）与基础目录拼接
3. 读取实际的资源文件内容

这就是为什么 read 命令必须输出 Base directory 的原因。

---

检查点 ✅

完成上述步骤后，请确认：

• [ ] 命令行显示了技能的完整 SKILL.md 内容
• [ ] 输出包含 Reading: <name> 和 Base directory: <path>
• [ ] 输出末尾有 Skill read: <name> 结束标记
• [ ] 多技能读取时，每个技能用空行分隔
• [ ] 优先读取项目本地技能而非全局技能

如果以上检查项都通过，恭喜你！你已经掌握了技能读取的核心流程。

---

踩坑提醒

问题 1：技能未找到

现象：

Error: Skill(s) not found: pdf

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

Install skills: npx openskills install owner/repo

原因：

• 技能未安装
• 技能名称拼写错误

解决方法：

1. 列出已安装技能：npx openskills list
2. 确认技能名称是否正确
3. 如果未安装，使用 openskills install 安装

---

问题 2：读取到错误的技能

现象：

期望读取项目技能，但实际读取到了全局技能。

原因：

• 项目目录不是正确的位置（使用了错误的目录）

解决方法：

1. 检查当前工作目录：pwd
2. 确保在正确的项目目录下
3. 使用 openskills list 查看技能的 location 标签

---

问题 3：多技能读取顺序不符合预期

现象：

npx openskills read skill-a,skill-b

期望先读取 skill-b，但实际先读取了 skill-a。

原因：

• read 命令按参数指定的顺序读取，不会自动排序

解决方法：

• 如果需要特定顺序，在命令中按顺序指定技能名

---

问题 4：SKILL.md 内容被截断

现象：

输出的 SKILL.md 内容不完整，缺少结尾部分。

原因：

• 技能文件损坏或格式错误
• 文件编码问题

解决方法：

1. 检查 SKILL.md 文件：cat .claude/skills/<name>/SKILL.md
2. 确认文件是否完整且格式正确（必须有 YAML frontmatter）
3. 重新安装技能：openskills update <name>

---

本课小结

通过本课，你学会了：

• 使用 openskills read <name> 读取已安装技能的内容
• 理解 4 级查找优先级：项目 universal > 全局 universal > 项目 claude > 全局 claude
• 支持多技能读取：使用逗号分隔技能名
• 输出格式：包含 Reading:、Base directory、技能内容、Skill read: 标记

核心概念：

概念	说明
查找优先级	4 个目录按顺序查找，返回第一个匹配
基础目录	AI 代理用于解析技能中相对路径的参考目录
多技能读取	逗号分隔，按指定顺序读取

核心命令：

命令	作用
npx openskills read <name>	读取单个技能
npx openskills read name1,name2	读取多个技能
npx openskills list	查看已安装技能及位置

---

下一课预告

下一课我们学习 命令详解。

你会学到：

• OpenSkills 所有命令的完整列表和参数
• 命令行标志的使用方法和作用
• 常用命令的快速参考

学会了如何使用技能后，接下来需要了解 OpenSkills 提供的所有命令和它们的作用。

---

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-24

功能	文件路径	行号
read 命令入口	src/commands/read.ts	8-48
技能查找（findSkill）	src/utils/skills.ts	69-84
技能名称规范化	src/utils/skill-names.ts	1-8
查找目录获取	src/utils/dirs.ts	18-25
CLI 命令定义	src/cli.ts	52-55

关键函数：

• readSkill(skillNames) - 读取技能到标准输出，支持多个技能名
• findSkill(skillName) - 按 4 级优先级查找技能，返回第一个匹配
• normalizeSkillNames(input) - 规范化技能名列表，支持逗号分隔和去重
• getSearchDirs() - 返回 4 个查找目录，按优先级排序

关键类型：

• SkillLocation - 技能位置信息，包含 path、baseDir、source

目录优先级（从 dirs.ts:18-24）：

[
  process.cwd() + '/.agent/skills',   // 1. Project universal
  homedir() + '/.agent/skills',       // 2. Global universal
  process.cwd() + '/.claude/skills',  // 3. Project claude
  homedir() + '/.claude/skills',      // 4. Global claude
]