api-connector-builder

api-connector-builder 技能總覽

api-connector-builder 是一個貼近 repo 的技能，適合在不偏離主程式碼庫既有整合模式的前提下，新增 API connector、provider 或 plugin。它最適合需要在既有系統裡再交付一個整合的工程師，不適合從零打造獨立的 HTTP client。它的核心工作很單純：把專案的 connector 版型、授權模型、設定格式、錯誤處理與註冊流程對齊，讓新的整合在第一次審查時就看起來像原生的一部分。

這個 api-connector-builder 技能是做什麼的

當目標 repo 已經有清楚的 connector 架構，而你需要一致地擴充它時，就使用 api-connector-builder skill。它最有幫助的情況不是 API 呼叫本身有多難，而是要符合專案在探索方式、測試與串接上的慣例。

什麼情況下最適合使用

如果你要在既有整合框架裡新增 Jira、Slack 或類似 provider，尤其 repo 裡已經有多個可運作範例時，這個技能很適合。對於 api-connector-builder for API Development 這類「模式比新意更重要」的任務，它的效果最好。

什麼情況會阻礙採用

如果你手上只有廠商文件，repo 內卻沒有任何範例，這個技能就會顯得力道不足，因為它的設計是複製專案既有風格，而不是憑空創造。當 repository 還沒有穩定的 connector 模式，或你想要的是通用 API client 而不是 repo 專屬的整合介面時，它也不是好選擇。

如何使用 api-connector-builder 技能

安裝後先從 repo 模式開始看

先在你的 Claude Code 環境中走 api-connector-builder install 流程，然後第一個打開 SKILL.md。因為這個技能是圍繞既有模式設計的，最先該看的不是外部 API 文件，而是同一個 repository 裡兩個以上現有 connector。這是最快理解命名、分層與預期介面的方式。

把模糊需求改寫成可用提示

弱的需求會說：「加一個 Slack connector。」更強的需求會說：「加一個符合現有 provider 模式的 Slack connector，支援 OAuth，提供 channel 與 message 的讀取操作，沿用 repo 的 retry 與 pagination 慣例，並補上測試與 registry wiring。」多補這些細節，能讓 api-connector-builder usage 更準，因為技能可以把實作範圍對齊宿主 repo，而不是靠猜。

先讀哪些檔案與訊號

先看 SKILL.md，再檢查附近是否有說明 connector、registration 或測試慣例的 repo 文件。在典型的 api-connector-builder guide 裡，最有價值的證據是現有 connector 的目錄結構、test fixtures，以及任何中央 registry 或 discovery code。如果 repo 裡有 README.md 或 AGENTS.md，要把它們當成政策來源，而不是現成範例的替代品。

通常最容易做出好結果的工作流程

先梳理專案風格：檔案布局、抽象邊界、設定 schema、retry 行為與命名方式。接著定義 repo 真正需要的最小整合面：授權、核心實體，以及必要的讀寫操作。然後用 repo 原生的層次來實作，讓 transport code、registration、測試與文件一起落地。這就是 api-connector-builder usage 的核心：不只是讓 API 能跑，而是讓它真的融入專案。

api-connector-builder 技能 FAQ

這個 repo 裡一定要有現成 connector 嗎？

通常是的。這個技能最有效的情況，是它能比較至少兩個現成範例，並推斷出目前的模式。如果 repository 只有一個 connector，或好幾個 connector 風格不一致，你可能得先放慢速度，先釐清 canonical style，再使用 api-connector-builder。

這和一般 prompt 有什麼不同？

有差。一般 prompt 也許能做出可用的整合，但 api-connector-builder skill 的目標是讓它在既有 codebase 裡保持一致性、可維護性與正確串接。當 reviewer 期待新 connector 的長相要跟系統其他部分一致，而不是像一次性的腳本時，這件事就很重要。

這個技能適合新手嗎？

如果你能照著模式走、也能比較範例，那它對新手算友善，但它不是那種「一個提示就完成」的技能。最常見的錯誤是跳過既有 connector，直接看 vendor docs，結果寫出一段離線可跑、卻不符合 repo 標準的程式。

什麼時候不該用它？

當你在建立全新的整合框架、重寫架構，或只是想做一個暫時性的 API script 原型時，就不要用它。這些情境下，必須配合既有模式反而是缺點，不是優點。

如何改進 api-connector-builder 技能

給技能正確而明確的目標範圍

最好的輸入是窄而清楚的：授權類型、實體、操作、pagination 規則、webhook 或 polling 預期，以及任何必要的 registry hook。如果你只提服務名稱，技能就得推測太多，容易做過頭，或漏掉必要的 repo 慣例。

避開最常見的失敗模式

最大的失敗模式包括：憑空做出第二套 connector 架構、只做到 transport code 就停、或直接照抄已過時的整合模式。想要更好的 api-connector-builder 結果，就要明確告訴它最接近的現有 connector 是哪一個，以及哪些部分必須完全保留，例如 config 形式、測試風格或錯誤對應方式。

第一版之後要迭代

先檢查第一版輸出這三件事：檔案布局是否符合 repo、是否有 client 以外的 wiring、以及是否只涵蓋最小可用範圍而沒有多餘功能。只要其中任何一項不對，就回覆修正，並指向要模仿的具體 in-repo 範例。這個回饋迴圈通常比籠統的「幫我改好一點」更能改善 api-connector-builder install 的結果。

要求的是證據，不只是程式碼

有力的後續追問會要求一段簡短說明：用了哪個既有 connector 當模板、匹配了哪些慣例、以及刻意省略了哪些內容。這能讓 reviewer 更容易做 api-connector-builder skill FAQ 的判斷，也能幫你確認結果是否真的是 repo-native。