Community写作与编辑github.com

kricha/knowledge-capture

智能体技能,用于在仓库本地保存原始的知识捕获记录。

knowledge-capture 是什么?

Knowledge Capture 是一款 AI 智能体技能,旨在帮助开发者在仓库内自动或按需捕获、更新和保存结构化的知识片段,如会话记录、讨论、调查、决策和交接。它支持 Claude Code、Cursor、Codex 等主流 AI 编码工具,通过遵循 `.ai/raw/` 下的固定目录结构和 `active-session.json` 指针文件,确保当前工作流的上下文持续可追踪。该技能的主要价值在于:每次任务完成时(若文件有变更、测试已运行或做出了决策/发现),自动创建或更新唯一一个活跃的“session”捕获,避免重复创建和上下文丢失。技能规则强调捕获内容的真实性和完整性——必须填写已知的字段(如用户请求、变更证据、决策和待办事项),禁止留下“未捕获”占位符;同时要求捕获最终状态而非中间过程,废弃的决策仅在解释实现代码、回滚或未解决问题时才保留。通过可选的 Node.js 命令行工具,用户可以快速创建、按路径更新或按指针更新捕获,并支持通过 stdin 传入 Markdown 格式的详细内容。该技能还内置了多项安全边界:禁止捕获敏感信息(如密钥、客户私人数据),避免逐字记录完整日志或庞大文件,以及使用 `agent_session_id` 作为工作流连续性的辅助判断。

兼容平台~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 版本中,不要读取、更新、去重、合并、同步、提交、发布或推广不相关的捕获。

仅因为助手写了一个文件并不意味着捕获已完成。不要在其已知事实的部分(特别是“用户请求”、“变更和证据”、“决策和发现”、“开放问题和后续步骤”)中留下“未捕获”。

更新活跃捕获时,应写入在当前工作流步骤之后捕获应呈现的完整内容。不要仅添加增量说明。使用当前任务上下文、可见文件、差异、测试、命令结果和交接文本作为证据;如果连续性不明确,请创建新捕获,而不是凭空捏造丢失的上下文。

保持捕获与当前事实对齐,而不是与每一个中间想法对齐。如果先前的决策已更改,且工作也随之更改,请捕获最终/当前的决策和证据。仅当被取代的决策能解释已实现的代码、回滚、未解决的风险或开放问题时,才保留该决策;省略纯粹理论上的、已被放弃的方案。

将捕获存储为 .ai/raw/<类型文件夹>/YYYY-MM-DDTHH-mm-ssZ--<类型>--<主题slug>.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 <路径> 替换已知的活跃捕获,或通过 --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

在标准输入上提供来自 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。

相关技能