Thariq Skills #1 — Library & API Reference：教 Agent 正確使用你的內部函式庫
Agent 最常在內部工具上踩坑——不是因為 agent 不聰明，而是因為它根本不知道你的 billing-lib 有哪些不能踩的陷阱。
這就是 Library & API Reference skills 要解決的問題。
類別定義
“How to correctly use a library, CLI, or SDKs. Often includes reference code snippets folder + gotchas list.”
這個類別覆蓋的是「agent 需要了解才能正確使用的內部或外部工具知識」。和官方文件不同，Library & API Reference skill 的重點不是完整性，而是高信號密度：
- 你的 API 有哪些非直覺的行為
- 常見的使用方式哪些是錯的
- 這個 CLI 有哪些版本差異要注意
- 哪些參數組合在你的環境下不適用
Thariq 的範例
Anthropic 內部使用的三個例子：
billing-lib — 內部計費函式庫的使用參考。重點不在完整 API 文件，而是「你以為可以這樣呼叫但其實不行」的清單。
internal-platform-cli — 內部平台 CLI 的操作指南。包含特定指令組合的副作用，以及在不同環境下的行為差異。
frontend-design — 前端設計規範 skill。Thariq 舉的具體例子是：「避免使用 Inter 字體和紫色漸層」——這不是一般文件會寫的，卻是讓 agent 設計結果符合預期最有效的一行。
為什麼不只是貼文件連結
很多人的直覺是：給 agent 文件連結就好了，讓它自己讀。Thariq 在 Thariq — Seeing like an Agent 裡描述了這個方法的問題——agent 讀文件連結通常載入太多無關的結果，context 充斥噪音。
Library & API Reference skill 解決這個問題的方式是提前策展：一個熟悉這個工具的工程師，花幾個小時把真正重要的部分整理成 skill。這個投資一次，之後每次 agent 使用這個工具都受益。
「Worth having an engineer spend a week making these excellent.」對 Product Verification 這樣說，但同樣適用 Library skills：人工投入一次，agent 效益長期累積。
推薦結構
billing-lib/
├── SKILL.md ← 高層概述 + 最重要的 gotchas
├── api-reference.md ← 函式簽名與參數說明
├── gotchas.md ← 累積的失敗模式（最高信號的檔案）
└── assets/
└── examples/ ← 可參考的程式碼片段SKILL.md 告訴 Claude 這個資料夾有什麼，Claude 會在需要時讀取對應的子檔案。這就是 Thariq 說的「漸進式揭露（Progressive Disclosure）」——不把所有 context 一次塞進去。
SuperPortia 實戰觀點
SP 目前與這個類別相關的 skills 主要是 superportia-ui 和 dev-workflow。兩者都有基本的操作說明，但都缺少 Thariq 最強調的核心元素：Gotchas 區塊。
具體的缺口：
| 工具 | 現狀 | 缺什麼 |
|---|---|---|
| Cloudflare Workers API | 分散在各 repo | 無正式 skill，缺 Gotchas |
| D1 Database | dev-workflow 有基本說明 | 缺版本差異記錄、缺 binding 陷阱 |
| SuperPortia Bridge API | 無 skill | Agent 每次都從零重新理解 |
| Astro 內容 API | 無 skill | content.config.ts schema 每次需重讀 |
最大的問題是：SP 的 skills 在 description 欄位寫的是「這個 skill 做什麼」，但正確的寫法是「什麼情況下應該觸發這個 skill」。這導致 Claude 在需要時不一定會自動載入正確的 skill。
為 Cloudflare D1 + Workers 建立一個獨立的cf-platform skill，包含：
（1）D1 binding 的正確語法（容易因版本變動踩坑）
（2）wrangler.toml 設定的常見錯誤
（3）Workers 環境變數 vs. Secrets 的使用邊界
從最近踩過的坑開始填，3-5 條就有效。
回到總文
本文是九大類別系列的第一篇。完整框架與 SuperPortia 對照請見：
...建立一個可重複執行的驗證 skill。 九篇分文導覽 以下每篇文章深入探討一個類別，包含 Thariq 的原始框架、範例解析、以及 SuperPortia 的實戰對照： 1. [[Thariq Skills — Library & API Reference]] — 如何教 agent 用好內部函式庫 2. [[Thariq Skills — Product Verification]] —...