使用技能

學完你能做什麼

• 使用 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
]