列出已安裝技能

學完你能做什麼

• 使用 openskills list 檢視所有已安裝的技能
• 理解 (project) 和 (global) 位置標籤的區別
• 快速統計專案技能和全域技能的數量
• 判斷技能是否安裝成功

你現在的困境

安裝了幾個技能後，你可能遇到這些問題：

• 「我剛才安裝了哪些技能？忘記了」
• 「這個技能是安裝到專案還是全域了？」
• 「為什麼某些技能在 A 專案能看到，在 B 專案看不到？」
• 「我想刪除一些用不到的技能，但不知道具體名字」

openskills list 指令就是為了解決這些疑惑——它像技能的「目錄」，幫你一目了然地看到所有已安裝的技能及其位置。

什麼時候用這一招

情境	動作
安裝技能後確認是否成功	執行 openskills list 檢視技能是否出現
切換到新專案，檢查可用技能	執行 openskills list 看看有哪些 project 技能
清理技能前先盤點	執行 openskills list 列出所有技能，再刪除不需要的
除錯技能載入問題	確認技能名和安裝位置是否正確

核心思路

OpenSkills 支援在4 個位置安裝技能（按查找優先順序）：

1. project .agent/skills - 專案級的通用技能目錄（多代理環境）
2. global .agent/skills - 全域的通用技能目錄（多代理環境）
3. project .claude/skills - 專案級的 Claude Code 技能目錄
4. global .claude/skills - 全域的 Claude Code 技能目錄

openskills list 會：

1. 遍歷這 4 個目錄查找所有技能
2. 去重：同一個技能名只顯示一次（優先顯示 project 的）
3. 排序：project 技能在前，global 技能在後；同一位置內按字母順序
4. 標記位置：用 (project) 和 (global) 標籤區分
5. 統計彙總：顯示 project 技能數、global 技能數和總數

為什麼需要去重？

如果你在 project 和 global 都安裝了同一個技能（例如 pdf），OpenSkills 會優先使用 project 版本。list 指令只顯示一次，避免混淆。

跟我做

第 1 步：列出所有已安裝技能

為什麼 快速檢視當前環境下有哪些技能可用

執行以下指令：

npx openskills list

你應該看到

如果沒有安裝任何技能，會顯示：

Available Skills:

No skills installed.

Install skills:
  npx openskills install anthropics/skills         # Project (default)
  npx openskills install owner/skill --global     # Global (advanced)

如果已安裝技能，會看到類似：

Available Skills:

  pdf                         (project)
    Comprehensive PDF manipulation toolkit for extracting text and tables...

  code-analyzer                (project)
    Static code analysis tool for identifying security vulnerabilities...

  email-reader                 (global)
    Read email content and attachments via IMAP protocol...

Summary: 2 project, 1 global (3 total)

第 2 步：理解輸出格式

為什麼 知道每行代表什麼含義，才能快速定位需要的資訊

輸出格式說明：

部分	說明
pdf	技能名稱（從 SKILL.md 的 name 欄位擷取）
(project)	位置標籤：藍色表示專案級技能，灰色表示全域技能
Comprehensive PDF...	技能描述（從 SKILL.md 的 description 欄位擷取）
Summary: 2 project, 1 global (3 total)	統計彙總：project 技能數、global 技能數、總數

第 3 步：驗證位置標籤

為什麼 確認技能安裝到了預期位置，避免「為什麼這個專案看不到這個技能」的疑惑

嘗試以下操作來理解位置標籤：

# 1. 安裝一個專案級技能
npx openskills install anthropics/skills -y

# 2. 檢視列表（應該顯示 project 標籤）
npx openskills list

# 3. 安裝一個全域技能
npx openskills install anthropics/skills --global -y

# 4. 再次檢視列表（兩個 pdf 技能，只顯示一次，標籤為 project）
npx openskills list

你應該看到

Available Skills:

  pdf                         (project)
    Comprehensive PDF manipulation toolkit for extracting text...

Summary: 1 project, 0 global (1 total)

即使全域和專案都安裝了同一個技能，list 指令也只會顯示一次，因為 project 版本優先順序更高。

檢查點 ✅

確認以下內容：

• [ ] 執行 openskills list 能看到已安裝的技能列表
• [ ] 能區分 (project) 和 (global) 標籤（顏色不同：藍色 vs 灰色）
• [ ] Summary 統計數字正確（project 技能數 + global 技能數 = 總數）
• [ ] 理解同一個技能名只顯示一次的規則

踩坑提醒

常見問題 1：找不到剛安裝的技能

現象：執行 install 指令成功，但 list 看不到

排查步驟：

1. 檢查是否在正確的專案目錄下（project 技能只對當前專案可見）
2. 確認是否安裝到了全域（用 --global 旗標）
3. 驗證安裝位置：

# 檢查專案目錄
ls -la .claude/skills/

# 檢查全域目錄
ls -la ~/.claude/skills/

常見問題 2：看到奇怪的技能名

現象：技能名不是你預期的（例如資料夾名 vs SKILL.md 中的 name）

原因：OpenSkills 使用 SKILL.md 中的 name 欄位作為技能名，而不是資料夾名

解決方法：檢查 SKILL.md 的 frontmatter：

---
name: pdf  # 這是 list 指令顯示的名稱
description: Comprehensive PDF manipulation toolkit...
---

常見問題 3：描述顯示不全

現象：技能描述被截斷了

原因：這是終端機寬度的限制，不影響技能內容

解決方法：直接檢視 SKILL.md 檔案獲取完整描述

本課小結

openskills list 是技能管理的「目錄」指令，幫你：

• 📋 檢視所有技能：一目了然地看到已安裝技能
• 🏷️ 區分位置標籤：(project) 表示專案級，(global) 表示全域級
• 📊 統計彙總：快速了解 project 和 global 技能的數量
• 🔍 排查問題：驗證技能是否安裝成功，定位技能位置

核心規則：

1. 同名技能只顯示一次（project 優先）
2. project 技能在前，global 技能在後
3. 同一位置內按字母順序排列

下一課預告

下一課我們學習 更新技能。

你會學到：

• 如何從來源儲存庫重新整理已安裝技能
• 批次更新所有技能
• 處理無元資料的舊技能

---

附錄：原始碼參考

點擊展開檢視原始碼位置

更新時間：2026-01-24

功能	檔案路徑	行號
list 指令實作	src/commands/list.ts	7-43
查找所有技能	src/utils/skills.ts	30-64
搜尋目錄設定	src/utils/dirs.ts	18-25
Skill 型別定義	src/types.ts	1-6

關鍵函式：

• listSkills()：列出所有已安裝技能，格式化輸出
• findAllSkills()：遍歷 4 個搜尋目錄，收集所有技能
• getSearchDirs()：回傳 4 個搜尋目錄路徑（按優先順序）

關鍵常數：

• 無（搜尋目錄路徑是動態計算的）

核心邏輯：

1. 去重機制：使用 Set 記錄已處理的技能名（skills.ts:32-33, 43, 57）
2. 位置判斷：透過 dir.includes(process.cwd()) 判斷是否為 project 目錄（skills.ts:48）
3. 排序規則：project 優先，同位置按字母順序（list.ts:21-26）