技能挖掘：從 3,500 個候選項目到 466 項能力

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

3,500 項技能的難題

當我們開始打造代理人協調系統時，遇到了一個有趣的挑戰：整個 AI 生態系中散落著成千上萬個潛在技能。GitHub 儲存庫、廠商文件、社群專案、內部經驗模式 — 技能無所不在。但哪些才真正重要？哪些真的有效？又該如何維護一套代理人真正能派上用場的一致技能庫？

我們的答案是：一套系統化的挖掘與導入迴圈。

今天的數字

在 Anthropic 於 2025 年 10 月 16 日推出 Agent Skills 剛滿三個多月後，本文於 2026 年 1 月 27 日發布時，我們的現況如下：

指標	數量
已識別候選項目	3,500+
已採納技能	466
廠商技能	373
內部技能	93
活躍廠商	25+
每項技能平均 token 數	2,834
參照工具數	89
不重複標籤數	635

我們審核了超過 3,500 個技能候選項目，最終採納了 466 項，採納率為 13% — 這樣的高度篩選是刻意設計的結果。

知識分層系統

並非所有技能生而平等，我們將它們組織成五個知識層級（K0 至 K4），各自代表不同的適用範圍：

K0：基礎（通用）

每個代理人都應具備的技能，代表能在任何地方都適用的「優秀思考者」能力。

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 技能可移植到任何專案、任何領域、任何技術堆疊，它們編碼的是通用的認知模式。

K1：身份（紀律）

「優秀工程師」或「優秀研究者」等，適用於某一學科內各個專案的技能。

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2：領域（專業知識）

「優秀的資料庫專家」或「優秀的安全工程師」等，可在某一領域內移植的技能。

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3：技術堆疊（技術）

「優秀的 Supabase 使用者」或「優秀的 Cloudflare 開發者」等，針對特定技術堆疊的技能。

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4：專案（組織）

專屬於我們組織與工作流程的技能。

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

挖掘迴圈

第一階段：發現

技能來自四面八方：

廠商儲存庫：AWS、Anthropic、Cloudflare、Supabase 以及社群貢獻者，都會發布技能集合，我們追蹤超過 25 個廠商根目錄。

社群專案：GitHub 上充滿了 Claude Code 範本、代理人模式與工作流程定義。

內部經驗模式：隨著我們團隊解決問題，各種模式會逐漸浮現，並被正式化為技能。

文件挖掘：技術文件中經常隱含著技能 — 程序、檢查清單、決策樹。

發現過程持續不斷，我們會用一份技能待辦清單，在正式評估之前追蹤候選項目。

第二階段：評估

每個候選項目都會經過同一套量規：

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

五項產品標準必須全數通過，這正是 87% 的候選項目遭到否決的原因。

接著，每個候選項目還會經過一次獨立的信任審查。我們不會把官方廠商儲存庫、知名的社群維護者，以及隨機的 GitHub 儲存庫，視為同等可信的來源。

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

受信任的廠商能獲得較輕量的來源審查，但這不代表可以免審通過。不受信任或來源不明的技能，則會經過更深入的人工稽核，而且在腳本被讀過、確認範圍、並歸類為安全之前，我們絕不會執行隨附的腳本。

缺口分析：在採納之前，我們會先搜尋自己的登錄檔：

uv run orkestra skills search "<capability>"

如果我們已經有了，就不需要再採納；如果我們有相近的東西，我們可能會選擇合併，而非直接採納。

深度與規範評分：我們也會為候選項目對代理人技能模型的運用完整度評分。單一的 SKILL.md 依然可能有用，但若能依照 agentskills.io 所鼓勵的方式，將指令與參考資料、腳本、素材分開，技能就會更有價值、更深入。

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub 星數可以稍微提升可信度分數，但永遠救不回一個膚淺或不安全的技能。一個星數很高、卻只有一句含糊的 SKILL.md 和不透明腳本的儲存庫，其分數會低於一個規模較小、卻擁有精確說明、精心整理的 references/、以及真正充分運用技能完整能力的原子化輔助工具的儲存庫。

結構分析：我們會檢查技能的品質：

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

若候選項目包含腳本，審查就會更加嚴格。一項好的技能不只要有用，還必須清晰易讀、範圍受限，且能安全地交給代理人使用。光是這道安全篩選，就足以刷掉相當一部分原本看起來頗有意思的候選項目。

第三階段：導入

當一項技能通過評估後，就會進入登錄檔。但技能從不會原封不動地被採納，而是會經過調整以符合我們的系統。

採納時的調整：

1. 中繼資料正規化：每項技能都會套用我們的前置資料結構描述
2. K 層級指派：技能會被歸入適當的知識層級
3. 標籤擴充：加入標籤以利於被發現
4. 工具宣告：明確宣告允許使用的工具
5. 章節對齊：內容會被重新組織，以符合我們的範本

導入後典型的技能 YAML 範例如下：

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

第四階段：範圍指派

技能會被指派到「範圍」— 決定哪些代理人會載入哪些技能的分類：

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

代理人會宣告自己的範圍，技能則會自動被指派：

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

第五階段：實體化

技能在正式環境中並非以 YAML 形式存在，而是會被渲染為 Claude Code 能夠載入的 SKILL.md 檔案：

uv run orkestra sync

這個指令會：

1. 讀取所有技能的 YAML 定義
2. 透過 Jinja 範本進行渲染
3. 將 SKILL.md 檔案寫入 .claude/skills/
4. 依 K 層級組織（foundations/、identities/、domains/、stacks/、project/）

最終的輸出結構如下：

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

休眠範圍模式

我們最強大的模式之一，是「已採納但未載入」的技能，我們稱之為休眠範圍。

以來自 k-dense-scientific 儲存庫的科學運算技能為例：我們已採納超過 120 項技能，涵蓋生物資訊學、化學、量子運算與臨床資訊學。但我們大多數代理人並不需要分子對接或基因表現分析。

我們並不會把全部 120 項技能都載入每一個代理人（那會撐爆情境視窗），而是：

1. 以特定範圍（例如 bioinformatics）採納這些技能
2. 讓它們保持休眠 — 已登錄但未載入
3. 只在代理人宣告該範圍時才啟用它們

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

這個模式讓我們的登錄檔中能容納 466 項技能，而一般代理人卻只會載入其中 40 到 60 項相關的技能。

技能類型

技能有三種認知模式：

工作流程

有序的程序性步驟：「1. 做 X，2. 接著做 Y，3. 最後做 Z」

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

紀律

行為護欄：「務必做 X」「絕不做 Y」「優先選擇 Z」

type: discipline
# Examples: test-first-discipline, evidence-based-completion

檢查清單

驗證標準：「確認 X」「驗證 Y」「檢查 Z」

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

品質關卡

每項技能在發布前都必須通過驗證：

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

說明文字必須介於 50 到 400 字元之間，並包含觸發語句（例如「Use when…」「When you need…」），讓 Claude Code 知道何時該建議使用它。

我們會持續進行驗證：

uv run orkestra validate --show-warnings

廠商生態系

我們的 373 項廠商技能，來源如下：

廠商	技能數	領域
AWS Agent	19	雲端服務
Anthropic	12	文件生成
Cloudflare	8	邊緣運算
Supabase	5	資料庫
k-dense	100+	科學運算
silvainfm	4	資料科學
Java Developer Kit	45+	Spring／Java
Vercel	1	瀏覽器自動化

每個廠商根目錄都會在 metadata.yaml 中宣告：

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

當 orkestra sync 執行時，廠商技能會依各自的廠商命名空間，以符號連結方式連進 .claude/skills/vendor/。

我們學到的事

高度篩選有其回報。 把每個看起來有用的東西都採納進來，是很誘人的做法，但每項技能都要耗費 token。以平均每項技能 2,834 個 token 來說，膨脹的代價很快就會浮現。我們 13% 的採納率，讓代理人保持精簡。

結構能促進發現。 K 層級系統不只是為了分類，更關乎可移植性。K0 技能可以在任何地方重複使用；K4 技能則刻意侷限於特定專案。這樣的清晰度，讓人類與代理人都能更容易找到自己需要的東西。

休眠範圍具備擴展性。 你可以採納數百項技能，卻不必全部載入。範圍機制讓你能建立一套涵蓋全面的登錄檔，同時讓每個代理人各自的情境視窗維持在可管理的範圍內。

採納時的調整不可或缺。 未經處理的原始廠商技能，很少能直接契合你的系統。導入流程 — 加入中繼資料、指派層級、擴充標籤 — 讓外部技能得以在內部順利運作。

挖掘是持續進行的。 3,500 這個數字仍在持續成長：新的廠商儲存庫不斷出現，社群模式不斷浮現，內部工作流程也不斷成形。這個迴圈永不停止。

接下來的計畫

我們正在推進幾項改進：

1. 自動化缺口偵測：當常見的代理人失誤本可透過某項尚未採納的技能解決時，發出警示
2. 技能淘汰流程：為已被取代或不再使用的技能，建立正式的退役程序
3. 跨技能依賴關係：明確宣告技能之間的前置需求
4. 使用分析：追蹤代理人實際呼叫了哪些技能，而不只是載入了哪些

技能挖掘迴圈是一種基礎建設，並不光鮮亮麗，但正是它，讓 41 個代理人能在情境限制內，與 466 項能力協調一致地運作。

這就是 3,500 如何變成 466 的故事：不是靠忽略其中的 3,000 個，而是靠系統化地逐一評估、只採納真正有效的那些。

---

想親眼看看這套技能系統實際運作嗎？歡迎查看 uv run orkestra skills list，探索我們目前的登錄檔。