grill-with-docs

grill-with-docs skill 概覽

grill-with-docs 是一個規劃與文件撰寫技能，適合想拿既有 repo 裡的語言與決策來反覆檢驗設計的團隊。它特別適用於 Technical Writing、重視產品語境的工程工作，以及 AI 輔助的架構討論；在這些情境裡，術語需要和 CONTEXT.md、ADRs 保持一致，而不是漂向空泛的「只靠 prompt」式表述。

它的核心工作很單純：一次只問使用者一個問題、提供建議答案，並在問題能從原始碼或文件得到解答時直接使用 codebase 或 docs。這讓 grill-with-docs 在真正風險是術語不一致、未明說的假設，或過時的決策紀錄時，比一般的腦力激盪 prompt 更有用。

grill-with-docs 有什麼不同

它不是只靠對話，而是以領域理解為核心。這個技能會推著你去看既有的 context 檔、掃描 ADRs，並在決策逐漸明朗時同步更新文件；也因此，它很適合 grill-with-docs for Technical Writing 這類文件密集型工作流程。

最適合的使用情境

當你需要以下任一項時，建議使用 grill-with-docs：

• 驗證某個計畫是否符合既有的領域模型，
• 選出精準的專案術語，
• 在決策做出的當下就把它記錄下來，
• 或是在實作開始前，先讓草稿和既有文件對齊。

不適合使用的情況

如果你只是想要快速摘要、潤飾過的規格文件，或不需要 repo 基礎、偏自由發想的構思過程，這個技能會比一般 prompt 慢一些。它的價值來自有紀律的提問，以及對文件脈絡的檢查。

如何使用 grill-with-docs skill

安裝 grill-with-docs

先用 repo 的標準 skill 管理器，把 grill-with-docs 安裝到你的 skills 目錄，接著在目標專案的脈絡中打開 skill 檔案。基本安裝方式如下：

npx skills add mattpocock/skills --skill grill-with-docs

可以先把它當作 grill-with-docs install 的起點，再確認這個 skill 在你實際使用的 agent 環境中已可用。

先用對的輸入開始

這個技能最適合從一則包含下列資訊的第一則訊息開始：

• 你正在規劃的目標，
• 系統或功能名稱，
• 任何已知且重要的術語，
• 以及你想釐清的決策邊界。

弱的 prompt 會這樣說：「幫我設計這個功能。」
更強的 prompt 會這樣說：「請用 grill-with-docs 先針對目前的 billing domain 檢查這個功能規劃。我需要確認 ‘subscription period’ 的正確術語、資料結構，以及在我寫文件前，哪些決策值得寫成 ADR。」

先讀這些檔案

對於 grill-with-docs usage，請先看：

• SKILL.md：了解訪談行為與工作流程，
• CONTEXT.md 或 CONTEXT-MAP.md：掌握目前的領域模型，
• docs/adr/：查看過去的決策，
• ADR-FORMAT.md 和 CONTEXT-FORMAT.md：如果你需要建立或更新檔案時參考。

這些檔案會告訴你哪些內容可以從 repository 推導出來，哪些內容必須明確寫下來。

能提升輸出的工作流程

把這個 skill 放進迴圈裡使用：

1. 先提供具體計畫或粗略草稿，
2. 讓 skill 一次只問一個問題，
3. 用最具體、且能對應 repo 的細節作答，
4. 當問題能從檔案中回答時，允許它探索 codebase，
5. 把術語與難度高的決策記到 context 或 ADR note 裡。

一個很實用的技巧是：把「我們需要一個名稱」和「我們需要一個決策」分開。這樣可以讓 grill 保持聚焦，也能避免不必要地新增 ADR。

grill-with-docs skill FAQ

grill-with-docs 只適合文件團隊嗎？

不是。只要某個計畫必須符合既有的領域詞彙，它就很有用，尤其是在 product engineering、platform work，或 grill-with-docs for Technical Writing 這類工作流程中；這些情境裡，措辭與結構都會影響後續的理解清晰度。

這和一般 prompt 有什麼不同？

一般 prompt 可以產生想法，但 grill-with-docs 的設計目標是追問假設、檢查 repository，並用既有脈絡把術語收緊。這能降低命名衝突，以及文件和 codebase 打架的機率。

需要成熟的文件系統才能使用嗎？

不需要，但如果 CONTEXT.md 和 ADRs 已經存在，效果通常最好。若還沒有，這個 skill 也可以在決策逐步浮現時，幫你慢慢定義它們。

什麼時候應該避免使用？

如果任務純粹是探索性質、repository 沒有足夠有意義的領域脈絡，或者你需要的是快速的一次性答案而不是結構化訪談，就不建議使用它。

如何改善 grill-with-docs skill

提供更好的決策素材

最大的品質提升，來自於給這個 skill 一個更窄、明確朝向決策的 prompt。請包含功能名稱、它會影響系統的哪一部分，以及你想解決的具體歧義。範例：我們在 accounting context 裡，應該把這個稱為 invoice、billing record，還是 charge？這個決策應該記錄在哪裡？

及早提供 repo 證據

如果你已經知道相關檔案，請一開始就直接提到。把 skill 指向 CONTEXT.md、某份特定 ADR，或像 src/billing/ 這樣的資料夾，能幫它少問一些空泛問題，多問一些真正有用的問題。這對 grill-with-docs usage 特別重要，因為這個 skill 最強的地方，就是能拿你的計畫去對照既有術語與結構。

留意常見失敗模式

最常見的失敗模式，是把領域描述得太寬，導致訪談一直停留在抽象層次。另一個問題，是在語言模型還沒掌握正確術語前，就急著問實作細節。如果第一輪輸出看起來太廣，請把決策重述得更精準，並要求 skill 接著上一個已解決的分支繼續。

從第一輪結果持續迭代

第一輪結束後，把答案整理成三種輸出之一：整理過的 glossary 條目、簡短 ADR，或修訂後的實作簡報。接著再用 grill-with-docs 針對尚未解決的問題跑第二輪。通常第二輪才是這個 skill 最能發揮價值的地方，因為那時術語與邊界已經更清楚了。