Knowledge Workflow Skills 使用笔记

choral-io/choral-skills 中的 knowledge-workflow 系列技能（Skills）不是一套文档模板，而是一套面向智能体（Agent）协作开发的上下文治理（Context Governance）方法。它把项目事实、设计判断、团队任务、交付状态和成员本地执行记录放回仓库（Repository）里，用普通的 Markdown 文件承载，再用不同的 Skill 约束读取、写入、审查和交付的边界。

这套方法要解决的不是“怎样让 Agent 记住更多聊天记录”，而是“怎样让一个项目在多轮对话、多名成员、多次交付之后仍然有可检查、可审查、可修正的上下文”。聊天上下文会过期，外部记忆会漂移，检索索引也可能只回答片段。仓库内的知识文件则可以像代码一样被查看、评审、提交和回滚。

核心思路

Knowledge Workflow（知识工作流）把“项目知识”看成工程资产，而不是对话副产物。一次需求讨论、一次技术判断、一次实现交付，最后都应该落到某种可维护的位置上：产品说明、设计文档、架构决策、任务条目、看板（Kanban）状态、审查记录，或者成员自己的本地工作日志。

它特别强调团队协作。团队协作中的问题往往不只是“谁来写代码”，还包括这些问题：

• 这个需求是否已经被接受？
• 当前任务是否真的准备好执行？
• 哪些资料是项目事实，哪些只是个人草稿？
• 实现完成后由谁审查？
• 看板移动是否经过批准？
• 本地执行记录能不能进入共享知识？
• Agent 下一次接手时应该读哪里，而不是重新猜一遍？

因此，Knowledge Workflow 的重点是上下文治理，而不是自动化本身。Agent 可以帮助维护知识，但不能把所有对话都自动变成共享事实；Agent 可以执行任务，但不能绕过团队约定、审查和看板批准。

即便是在个人项目里，这套流程也有价值。个人开发常常会同时扮演产品、架构、实现、审查和维护者。角色可以是同一个人，但分工仍然存在：规划要先于执行，任务要有边界，交付要有验证，长期知识要区别于临时笔记。全流程并不是为了增加仪式感，而是为了让未来的自己和未来的 Agent 能接上当前工作。

适用范围

Knowledge Workflow 适合长期演进、上下文容易丢失、需要多人或多角色协作的工作。典型收益是把“讨论过什么”“决定了什么”“接下来做什么”“做到什么程度”沉淀成仓库内可审查的记录。

它尤其适合以下场景：

• 产品或工程团队需要让 Agent 参与需求整理、任务规划、实现、审查和知识维护。
• 小团队希望把团队任务、交付状态和项目事实放在同一个可版本化的工作面上。
• 个人开发者希望让长期项目不依赖聊天记录和个人记忆，而是按规划、实现、审查、知识更新的节奏推进。
• 开源或跨仓库协作需要区分项目事实、任务候选、已接受任务、成员本地执行记录和维护者配置。

它不适合一次性问答、短期脚本、无需沉淀上下文的临时工作。流程本身有成本，只有当项目会持续演进、需要复盘或需要交接时，这些边界才会带来明显收益。

为什么

Knowledge Workflow 的出发点不是“再造一个项目管理工具”，而是把 Agent 和团队都需要反复读取的工作上下文放到仓库里。需求、设计资源、任务计划、项目事实、决策依据、任务来源、交付证据和本地执行边界，应该和代码一样可以被版本化、被审查、被链接、被修正。

这些内容集中在仓库知识库里，还有一个直接收益：团队成员可以快速检索当前项目到底有哪些需求、设计约束、任务计划和历史判断；AI Agent 也可以从同一组文件里快速检索并引入上下文，而不是依赖不完整的聊天记录或临时转述。上下文入口越稳定，Agent 越容易判断“该读什么、该改什么、哪些内容不能当成事实”。

外部工具仍然有自己的位置。项目管理和排期工具适合路线图、优先级、跨团队协调和管理视图，例如 Jira、Linear、GitHub Projects；Issue 和讨论系统适合公开反馈、缺陷跟踪、问题讨论和社区协作，例如 GitHub Issues、GitLab Issues；Wiki、文档站和知识库产品适合发布稳定文档、团队手册或面向读者的知识页，例如 GitHub Wiki、Notion、Confluence。它们都可以继续使用。

问题在于，这些工具通常不是 Agent 执行项目工作时最稳定的上下文层。项目管理卡片可能只保留摘要，Issue 讨论容易混合问题、猜测、决策和过期实现细节，Wiki 页面可能和代码、任务状态脱节，聊天记录和 Agent 记忆则更适合短期上下文和辅助回忆。它们能承载协作入口，但不一定能成为项目事实的可审查来源。

Knowledge Workflow 补的是这一层：仓库内、Markdown 优先、可比较差异（diff）、可评审（review）、可被 Agent 稳定读取的工作知识库。当外部工具里的信息变成项目依据时，应该沉淀到仓库知识库；当仓库任务需要对外协作时，也可以链接回外部 issue、项目管理卡片或文档页。这样外部工具负责协作入口和管理视图，仓库知识库负责项目上下文的长期治理。

仓库模型

一个使用 Knowledge Workflow 的仓库通常会有一个知识目录（Knowledge Directory），默认是 knowledge/。如果项目使用非默认目录，仓库根目录会有 .knowledge-workflow 作为引导指针。

几个关键文件和目录承担不同职责：

• <knowledge_dir>/.workflow/runtime.md：运行时规则（Runtime Rules），用于说明成员身份解析、路径约定和 Agent 工作入口。
• <knowledge_dir>/.workflow/manifest.yml：清单（Manifest），记录安装状态、受管理文件、本地目录、反馈模式和配置。
• <knowledge_dir>/.workflow/rules/：工作流规则，例如知识写入、交付、成员工作区边界。
• <knowledge_dir>/.workflow/schemas/：结构约束（Schemas），说明不同类型知识文件应该有哪些元数据和正文结构。
• <knowledge_dir>/discovery/：需求发现、市场或业务研究、客户上下文、机会判断和假设。
• <knowledge_dir>/product/：产品需求、功能定义和用户可见行为。
• <knowledge_dir>/design/：UI 视觉设计、组件规范、布局规则、设计系统判断和设计说明。
• <knowledge_dir>/concepts/：领域术语、概念解释和可复用的背景说明。
• <knowledge_dir>/architecture/：技术设计、模块边界和架构说明。
• <knowledge_dir>/decisions/：已经接受的产品或技术决策。
• <knowledge_dir>/guidelines/：跨分区的写作、术语、语言、文档和流程指南。
• <knowledge_dir>/assets/<asset-type>/<topic>/：设计稿、截图、原型导出、研究附件等支持资源；例如设计资源可以放在 <knowledge_dir>/assets/design/<feature-name>/，再由 design/ 下的 Markdown 文件链接。
• <knowledge_dir>/planning/KANBAN.md：团队看板，记录已经进入交付流程的任务状态。
• <knowledge_dir>/planning/：路线图、阶段计划、迭代（sprint）计划和总结；其中 KANBAN.md 是交付状态入口。
• <knowledge_dir>/proposals/：有价值但尚未确认的知识、任务或决策候选，作为进入正式分区前的评审缓冲区。
• <knowledge_dir>/tasks/*.md：任务条目（Task Items），保存任务目标、来源、验收标准、依赖关系和责任人。
• <knowledge_dir>/members/：团队成员、职责、关注领域和公开协作上下文。
• <knowledge_dir>/groups/：团队、评审小组、维护者组或其他非个人责任主体。
• <knowledge_dir>/workspace/：成员维度的共享总结、交接、研究和本地工作区；其中 <knowledge_dir>/workspace/<member-id>/local/ 用于个人工作清单、执行日志和临时状态，通常不进入版本控制。

这些分区来自 knowledge-workflow 默认的软件产品开发配置（profile）。实际仓库可以按项目需要裁剪或扩展。关键是每类知识都有明确归属：需求和用户行为放在 product/，探索材料放在 discovery/，视觉和交互设计说明放在 design/，设计导出物和附件放在 assets/，技术结构放在 architecture/，已接受判断放在 decisions/，交付任务放在 tasks/ 和 planning/，成员和责任主体放在 members/ 与 groups/，成员协作信息放在 workspace/。

这个模型里最重要的边界是“共享事实”和“本地执行状态”的区别。product/、architecture/、decisions/、tasks/、planning/KANBAN.md 这类内容可以成为团队共同依据；workspace/<member-id>/local/ 则是个人执行表面，不应该被其他成员或 Agent 当成项目事实。

如果知识库需要保存设计稿、截图、原型导出、研究附件等较大的二进制资源，可以根据团队习惯启用 Git LFS、对象存储链接或外部设计工具链接等方案。关键不是把所有东西都塞进 Git 普通对象里，而是让知识库保存稳定引用、说明这些资源如何被使用，并避免大文件拖慢仓库 clone、diff 和 CI。

安装与初始化

在支持 Skills 的运行时里，可以直接安装 choral-skills：

npx skills add choral-io/choral-skills

如果运行时支持插件（Plugin），也可以安装打包好的 knowledge-workflow 插件。

Claude Code：

claude plugin marketplace add choral-io/choral-skills
claude plugin install knowledge-workflow@choral-skills

Codex：

codex plugin marketplace add choral-io/choral-skills
codex plugin add knowledge-workflow@choral-skills

安装或升级 Skill 之后，需要重新启动 Agent 会话，让运行时加载新的 Skill。然后在目标仓库中使用 knowledge-workflow-admin 做初始化或检查：

使用 `knowledge-workflow-admin` 初始化本仓库的知识库。

如果仓库里可能已经存在旧版本安装，应该先检查，而不是直接重新初始化：

使用 `knowledge-workflow-admin` 检查本仓库已有的知识库安装状态。

这里有一个关键区别：升级 Skill 只会改变 Agent 会怎么工作，不会自动改写已经初始化的项目仓库。仓库侧的 .workflow/ 支持文件、清单和平台提示需要通过 knowledge-workflow-admin:check 或经过批准的迁移流程单独处理。

Skill 分工

Knowledge Workflow 把能力拆成多个 Skill，是为了让读、写、规划、执行、审查和管理有明确边界。

如果不知道该用哪个 Skill，从 knowledge-assistant 开始。它的价值不是替代所有 Skill，而是把请求路由到正确边界内。例如，想把一段讨论写进共享知识，先让它判断应该走 knowledge-intake 还是已经可以走 knowledge-capture；想把任务加入看板，先走 delivery-planning 产出建议，再由 kanban-maintenance 在批准后应用。

从想法到交付

一条想法进入项目后，不应该直接变成任务，也不应该直接进入实现。Knowledge Workflow 把这个过程拆成几段：先判断材料是否值得沉淀，再把已确认的知识写到合适位置；当它需要交付时，先形成任务候选和看板建议；进入看板后，再选择、实现、审查，最后在批准后完成状态更新。

这里的 dry-run 指只预演和报告计划，不直接写入共享知识或修改看板。

这个流程里的每一步都有明确边界。knowledge-intake 不替你写共享事实，delivery-planning 不直接改看板，delivery-review 不默认替实现者修问题，kanban-maintenance 只应用已经批准的状态变化。边界看起来繁琐，但它正是团队协作和长期项目可维护性的来源。

常见案例

案例一：初始化新仓库

新项目要引入 Knowledge Workflow 时，不应该手写一堆目录然后让 Agent 猜规则。推荐流程是让维护者显式调用管理 Skill：

使用 `knowledge-workflow-admin` 初始化本仓库的知识库。

初始化前，knowledge-workflow-admin 应该确认知识目录、规范语言、平台提示文件和本地目录策略。初始化后，仓库会得到 .workflow/runtime.md、.workflow/manifest.yml、规则、模板、结构约束和初始看板等支持文件。之后团队成员再通过 knowledge-assistant 理解这个仓库的工作方式。

案例二：把讨论沉淀为共享知识

假设一次对话里形成了一个技术判断：“默认路径路由不能通过导入另一个路由文件（route file）实现，否则生产构建可能漏掉样式注入。”这类内容不应该只留在聊天里。

如果还不确定应该放到架构、指南、任务还是决策中，可以先说：

使用 `knowledge-intake` 判断这条发现应该进入哪类共享知识：
默认路径路由不能通过导入另一个路由文件（route file）实现，否则生产构建可能漏掉样式注入。

knowledge-intake 的作用是判断这段材料是否应成为共享知识、应该放在哪类文件、是否需要先补证据。等目标和写入方式确认后，再明确批准：

使用 `knowledge-capture` 将这条已批准的发现更新到路由指南中。

这样做的结果是，知识写入有来源、有归属、有批准，而不是由 Agent 在多个文档里自由发挥。

案例三：从需求材料进入团队任务

产品讨论、用户反馈或研究材料不等于可执行任务。Knowledge Workflow 会把“任务候选”和“已接受交付任务”区分开。

如果有一批需求材料，需要整理为看板候选，可以使用：

使用 `delivery-planning` 审阅这些任务候选，并以 `dry-run` 形式提出看板变更建议。

delivery-planning 会读取相关知识、任务条目和现有 planning/KANBAN.md，去重并产出 dry-run 表格。这个阶段只是建议，不应该直接移动看板。维护者确认后，再使用：

使用 `kanban-maintenance` 应用已经批准的看板变更。

这条边界对团队任务很重要。它防止 Agent 把未经接受的想法直接塞进 Ready，也防止一个人本地的 TODO 被误当成团队承诺。

案例四：选择下一项工作

当团队看板已经有任务，当前成员想知道下一步做什么，可以使用：

使用 `next-task-selection` 为我推荐下一项已被接受、适合继续处理的任务。

next-task-selection 会优先看 Ready 列，检查任务依赖、当前成员分配、任务元数据和阻塞关系。它推荐的是“已进入看板的已接受任务”，不是随便从 tasks/*.md 里挑一条看起来有趣的事项。

如果用户明确允许自动开始，仍然要检查任务是否处于 Ready 状态、是否有未解决依赖、是否存在脏工作区冲突、是否涉及敏感信息。推荐任务和开始实现是两个动作。

案例五：实现与审查

已经接受的任务进入实现阶段后，可以使用：

使用 `delivery-implementation` 实现这张已批准的看板任务卡。

这个 Skill 应该先读取看板卡片、任务条目、来源知识和验收标准，再检查相关代码或文档。实现后，它需要运行合适的检查，并判断是否需要同步更新知识。

实现完成不等于 Done。团队流程里通常还需要审查：

使用 `delivery-review` 根据任务验收标准审查这次实现。

delivery-review 会按问题优先的方式检查本地差异（diff）、测试、验收标准、知识更新和风险。即便实现者和审查者是同一个人，这一步仍有价值：它迫使自己切换角色，从“我刚写完”切换到“这个交付是否真的可以交给未来维护者”。

看板移动仍然是单独批准门。delivery-review 可以建议 Reviewing -> Done，但不应该擅自移动卡片。

案例六：个人本地工作清单

workspace-worklist 管理的是当前成员自己的本地工作流，例如今天要处理哪些事项、某个任务的执行日志、临时分解出来的个人步骤。

常见用法是：

使用 `workspace-worklist` 将这张分配给我的看板任务卡接收到本地工作清单。

或者：

使用 `workspace-worklist` 继续执行本地工作清单中的下一项 `Active` 工作。

这里的关键是本地（local）边界。workspace/<member-id>/local/WORKLIST.md 和日志适合记录个人执行状态，但它们不是团队事实，也不应该直接作为看板规划输入。如果某个本地发现需要进入团队知识，应该先总结或提升为共享材料，再走 knowledge-intake 或 knowledge-capture。

案例七：升级后的检查

当 choral-skills 中的 Skill 已经更新，目标仓库不会自动迁移。正确做法是先检查仓库侧状态：

使用 `knowledge-workflow-admin` 检查本仓库的知识库安装状态。

如果发现 .workflow/ 支持文件、清单或平台提示文件与当前基线不一致，管理 Skill 应该先给出迁移 dry-run，区分支持文件、项目事实和本地状态。只有维护者批准后，才应用变更。

这个原则可以避免一个常见风险：用新的模板覆盖旧仓库时，把项目自己积累的事实、成员规则或本地约定一并抹掉。

使用原则

第一，不确定时先路由。knowledge-assistant 是团队入口，不是所有问题都直接交给写入型 Skill。

第二，共享写入需要明确批准。knowledge-intake 可以判断材料去向，knowledge-capture 才负责批准后的写入。

第三，计划和应用分开。delivery-planning 产出 dry-run，kanban-maintenance 执行批准过的看板变更。

第四，执行和完成分开。delivery-implementation 可以让任务进入可审查状态，但 delivery-review 和看板批准决定它是否进入 Done。

第五，本地和共享分开。workspace-worklist 的 local/ 是个人执行状态，不应被提交，也不应直接变成团队事实。

第六，个人项目也要保留角色边界。一个人可以同时是维护者、开发者和审查者，但初始化、规划、实现、审查、知识更新仍然是不同阶段。区分阶段能减少上下文混乱，也让未来接手的 Agent 更容易判断当前工作真实状态。

提示词速查

初始化新仓库：

使用 `knowledge-workflow-admin` 初始化本仓库的知识库。

检查已有仓库：

使用 `knowledge-workflow-admin` 检查本仓库已有的知识库安装状态。

询问该用哪个 Skill：

使用 `knowledge-assistant` 判断这个请求应该交给哪个 Knowledge Workflow Skill。

判断一段材料是否应成为共享知识：

使用 `knowledge-intake` 判断这段项目笔记是否应该进入共享知识，以及应该放在哪里。

写入已批准的共享知识：

使用 `knowledge-capture` 写入这项已经批准的共享知识更新。

从任务候选提出看板建议：

使用 `delivery-planning` 以 `dry-run` 形式提出看板变更建议。

应用已批准的看板变更：

使用 `kanban-maintenance` 应用已经批准的看板变更。

选择下一项任务：

使用 `next-task-selection` 推荐下一项已接受且可继续处理的任务。

实现已接受任务：

使用 `delivery-implementation` 实现这张已批准的看板任务卡。

审查交付结果：

使用 `delivery-review` 审查这次实现是否满足交付要求。

管理个人本地工作清单：

使用 `workspace-worklist` 继续执行本地工作清单中的下一项 `Active` 工作。

小结

Knowledge Workflow 的价值不在于让 Agent 多写几个文件，而在于让项目上下文有边界、有来源、有状态、有审查路径。团队协作需要这些边界，个人项目在长期演进时同样需要。

当 Agent 工作越来越多地参与规划、实现和交付时，真正稀缺的不是一次回答里的上下文窗口，而是项目能否把重要上下文保存到正确位置，并在下一次工作开始时被可靠地重新读出来。knowledge-workflow 系列 Skills 正是在这个层面上提供约束和工具。