Community寫作與編輯github.com

kricha/knowledge-capture

用於儲存原始倉庫級知識記錄的代理技能。

knowledge-capture 是什麼?

「知識擷取」技能旨在為 AI 代理工具(如 Claude Code、Cursor、Codex 等,以及任何符合其標準腳本與工作流程的代理)提供一種結構化且可恢復的方式,來記錄在工作階段中發現的資訊、做出的決策、進行的調查以及執行的任務。其核心功能是自動化建立與更新「工作階段」記錄——在倉庫中儲存為純文字 Markdown 檔案。該技能會維護一個指向最新工作階段記錄的活動指標(`.ai/raw/active-session.json`),確保代理在連續的工作階段中能夠可靠地進行更新,而不是每次都建立新檔案。它強調只記錄與當前任務相關、準確的資訊,避免記錄整個對話或大型日誌,並且會明確排除機密資訊。該技能支援多種記錄類型(工作階段、討論、調查、決策、交接),並提供一個基於 Node.js 的輔助腳本,用於在可用時簡化建立與更新流程;但直接操作 Markdown 檔案同樣被認為是有效的。本質上,它為代理提供了一種輕量級、以倉庫為中心的知識管理功能,有助於在冗長或多階段的開發任務中保持情境連續性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add kricha/knowledge-capture

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

知識擷取

自動使用

在任何倉庫任務的最終回應之前,如果檔案已變更、測試已執行,或做出了決定/發現/後續事項,請為當前工作階段/工作流程建立或更新恰好一個活動中的 session 記錄。請在驗證之後、請求清理待辦事項或批准之前執行此操作。

不要僅因為技能被再次呼叫就建立一個全新的記錄。如果已知此工作流程的活動記錄路徑,請更新該檔案。否則,讀取 .ai/raw/active-session.json 作為候選的活動指標。如果不存在可靠的活動記錄,或工作流程明顯已變更,請建立一個新的原始記錄並取代該指標。

為後續使用記錄足夠的當前任務細節。僅讀取/更新當前工作流程的活動記錄;在 v0.2 版本中,請勿讀取、更新、去重、合併、同步、提交、發布或推廣不相關的記錄。

僅僅因為輔助程式寫入了檔案,並不代表記錄已完成。不要將已知事實的章節留空填寫 Not captured.,特別是「使用者請求」、「變更與證據」、「決定與發現」以及「開放性問題與後續步驟」。

在更新活動記錄時,請寫入整個記錄,使其呈現為當前工作流程步驟完成後應有的狀態。請勿僅附加增量備註。使用當前的任務上下文、可見檔案、差異、測試、命令結果和交接文字作為證據;如果連續性不明確,請建立一個新記錄,而不是憑空發明遺失的上下文。

使記錄與當前實際情況保持一致,而不是與每一個中間想法保持一致。如果先前的決定已更改,且相關工作也隨之更改,請記錄最終/當前的決定和證據。僅在它能夠解釋已實作的程式碼、回滾、未解決的風險或開放性問題時,才保留被取代的決定;請省略純粹理論上已被放棄的選項。

將記錄儲存為 .ai/raw/<類型資料夾>/YYYY-MM-DDTHH-mm-ssZ--<類型>--<主題短語>.md。如果確切的檔案名稱已存在,請在 .md 之前附加 --2、--3,以此類推。

類型:session -> sessions,discussion -> discussions,investigation -> investigations,decision -> decisions,handoff -> handoffs。

對於 session 記錄,維護 .ai/raw/active-session.json 作為指向活動工作流程記錄的本地指標。請勿在每次最終回應後清除它;它支援恢復、壓縮和交接。當新的工作流程記錄開始時,替換它。

記錄

將 /capture 視為建立/更新當前工作階段的記錄。當 <type> 為 session、discussion、investigation、decision 或 handoff 時,將 /capture <type> 視為該類型的記錄。

在上下文壓縮、壓縮或交接之前,如果重要的成果或決定尚未被記錄,請先進行記錄。

如果 Node 可用,這個無依賴的輔助程式可以建立第一個記錄、使用 --update <path> 取代已知的活動記錄,或使用 --update-active 取代指向的記錄。透過 --stdin 傳遞豐富的結構化章節細節,或直接撰寫 Markdown。預設情況下,輔助程式會阻止僅包含標題/摘要的記錄,因為這會遺失有用的工作階段知識。

node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --summary "Fixed expired refresh token behavior" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "auth refresh token fix" --update-active --stdin

在 stdin 上提供來自 references/raw-capture-schema.md 的 Markdown 標題。如果 Node 或 shell 執行不可用,請直接建立或更新 Markdown。

對於活動工作階段記錄,請使用此順序:

  1. 如果當前上下文中已知活動路徑,則更新該路徑。
  2. 否則,讀取 .ai/raw/active-session.json 作為候選指標。
  3. 如果指標和執行環境都暴露了一個 agent_session_id 且它們匹配,則更新它。
  4. 如果工作階段 ID 不同、缺失或不可用,但使用者請求或交接明確地持續同一工作流程,則更新它並重新整理指標。
  5. 否則,建立一個新記錄並取代指標。切勿透過猜測最新檔案名稱來選擇。

護欄

  • 記錄有用的原始細節,但避免記錄完整對話、大型日誌和整個檔案。
  • 將已變更的檔案、測試、命令和證據置於「變更與證據」下;當多個檔案變更時,按目的對檔案進行分組。
  • 僅包含罕見、不明顯或與決策相關的命令/結果;省略那些日後無關緊要的常規命令。
  • 僅為了使活動記錄準確有用而對其進行重組;不要捏造事實,或默默地將過時的理論當作仍然真實的內容保留。
  • 將 agent_session_id 視為一個有用的護欄,而不是工作流程的定義。一個新的代理工作階段可以繼續同一個工作流程。
  • 僅在執行環境明確暴露了一個穩定的當前工作階段、對話、執行緒或執行 ID 時,才使用 --agent-session-id。如果不可用,則省略它。切勿偽造一個。
  • 排除機密資訊、憑證、API 金鑰、私鑰、客戶私人資料和不相關的個人記憶。
  • 如果存在敏感內容,請勿建立記錄;先進行抽象總結。
  • 原始/本地狀態來自 .ai/raw/ 路徑和技能策略,而非來自每個記錄的工作流程欄位。
  • 將 Node 輔助程式視為可選項。直接建立檔案同樣有效。

儲存後,報告路徑、類型以及是建立還是更新。如果輔助程式阻止了記錄,請報告警告並且不要儲存原始內容。

參考資料

  • 僅在手動撰寫或更改結構時閱讀 references/raw-capture-schema.md。
  • 在不確定更新後的工作流程記錄應如何呈現時,閱讀 references/active-session-example.md。
  • 僅在將此技能改編給其他代理使用時,閱讀 references/agent-portability.md。

相關技能