Skill-Based Architecture是一个元技能框架，旨在解决AI代理在大型项目中面临的文档混乱、规则冲突和重复错误问题。通过结构化的知识组织和智能路由机制，它将项目规则、工作流程和经验教训蒸馏成可维护、可复用的技能模块，让每个代理在每次任务前都能获得恰到好处的上下文。

Skill-Based Architecture：为AI代理构建项目专属技能的知识蒸馏框架\n\n## AI代理文档化的困境\n\n随着Cursor、Claude Code、Codex、Windsurf等AI编程代理的普及，项目文档不再只是给人类开发者阅读的材料——它们成为了AI代理理解项目规则、遵循编码规范、执行复杂工作流的关键输入。然而，传统的文档组织方式在面对AI代理时暴露出了严重的问题。\n\nSkill-Based Architecture项目敏锐地识别了这些痛点：\n\n单一巨型文件问题。许多项目将所有规则塞进一个400多行的SKILL.md文件，导致代理在每次任务时都要读取全部内容，既浪费token又拖慢响应速度，维护起来也极其困难。\n\n规则分散与冲突。规则散落在AGENTS.md、.cursor/rules/、CLAUDE.md等多个位置，造成内容重复、规则矛盾，代理无法确定应该遵循哪个版本。\n\n只增不减的文档堆积。有用的规则被过时的内容淹没，代理无法辨别哪些规则仍然有效。\n\n被动描述vs主动触发。技能描述往往是静态摘要而非明确的激活条件，导致代理无法自动判断何时应该使用该技能。\n\n宝贵经验流失。调试过程中花费30分钟以上才解决的棘手问题，其解决方案往往被埋没在文档深处，无法在类似任务中自动浮现。\n\n缺乏事后复盘。工作中发现的教训没有被记录，同样的错误反复发生。\n\n叙事化而非结构化。经验教训以故事形式书写，而非可复用、可转移的结构化知识。\n\nSkill-Based Architecture正是为解决这些问题而设计的元技能框架。\n\n## 核心理念：输出即目的\n\nSkill-Based Architecture的核心理念可以用一句话概括："输出即目的"。它不仅仅是为了让文档更整洁，而是要生成一个真正理解项目的技能——这个技能具备路由能力、自我维护能力、经验捕获能力，并且能在任务匹配时自动触发。\n\n框架的工作流程非常直观：将你的项目指向skill-based-architecture，它会分析代码库，将项目的规则、工作流和宝贵经验蒸馏到一个专用的skills//目录中。生成的技能成为所有AI代理（Cursor、Claude Code、Codex、Windsurf、Gemini等）在执行任务前咨询的单一事实来源。\n\n## 三层可靠性模型\n\nSkill-Based Architecture明确了自己的定位：它解决的是AI代理可靠性的"上下文层"问题，而非全部问题。项目将代理可靠性分为三个层次：\n\n| 层次 | 解决的问题 | 本技能提供的支持 |\n|------|-----------|----------------| \n| 提示（Prompt） | 如何表述任务 | 间接——通过描述作为触发条件 |\n| 上下文（Context） | 如何向模型传递信息 | 主要关注点——路由、必读文件、薄包装、渐进式披露 |\n| 工具（Harness） | 周围系统如何保持执行稳定 | 部分——会话纪律+合理化表格+可选SessionStart钩子 = 最小化工具，用于长会话中的上下文重新注入 |\n\n当代理表现不稳定时，根本原因很少是模型本身。项目建议运行四原语审计：系统是否有状态跟踪、节点级验证、带检查点的编排、恢复路径？三个"否"意味着是工具问题而非模型问题。重新调整提示无法弥补缺失的工具。\n\n## 目录结构规范\n\nSkill-Based Architecture定义了一套清晰的目录结构：\n\n\nskills/<name>/\n├── SKILL.md # <=100行：必读列表 + 任务路由表\n├── rules/ # 长期约束（什么始终为真）\n├── workflows/ # 分步程序（如何做某事）\n├── references/ # 背景：架构、陷阱、索引\n│ └── gotchas.md # 已知陷阱——往往是最有价值的内容\n└── docs/ # 可选：提示、报告、外部文档\n\n\n根入口文件（AGENTS.md、CLAUDE.md、CODEX.md、.cursor/rules/.mdc、.codex/）变成"薄包装"——每个不超过15行，只包含路由表和指向正式技能的指针。\n\n## 双层阅读系统\n\nSKILL.md采用双层阅读系统，而非一次性加载所有文档：\n\n必读（Always Read）：2-3个文件，约150行，每个任务都必须加载。这通常包括rules/project-rules.md和rules/coding-standards.md。\n\n常见任务（Common Tasks）：按任务路由，代理只读取当前任务列出的文件。例如：\n\n| 任务 | 需要读取的文件 | 工作流 |\n|------|---------------|--------|\n| 修复bug | rules/project-rules.md + rules/coding-standards.md | workflows/fix-bug.md |\n| 添加功能 | rules/-rules.md | workflows/.md |\n\n每个入口文件嵌入路由表——不仅仅是"去读取SKILL.md"。这种设计在长对话中能够经受上下文摘要的考验，而自然语言指令往往会丢失。\n\n## 描述作为触发条件\n\n传统技能描述往往是被动摘要，如"帮助API测试"。Skill-Based Architecture要求描述成为明确的激活条件：\n\nyaml\n# 不好的描述——技能永远不会触发\ndescription: 帮助API测试\n\n# 好的描述——可靠激活\ndescription: >\n 当用户要求\"测试API端点\"、\"为REST API编写集成测试\"\n 或\"调试失败的HTTP请求\"时使用此技能。\n 当任务涉及HTTP状态码、请求/响应负载或API认证流程时激活。\n\n\n这种显式的触发条件让代理能够可靠地判断何时应该加载该技能。\n\n## 会话纪律与重新阅读规则\n\nSkill-Based Architecture强制执行严格的会话纪律：\n\n每个新任务——即使是同一会话中的第二个或第三个任务——必须重新阅读SKILL.md，重新匹配常见任务路由表，并重新读取该路由列出的所有文件。\n\n"我之前已经读过了"不是有效理由。上下文会被静默压缩；新任务可能匹配不同的路由；部分记忆比没有记忆更糟糕。重新阅读只需几秒钟，跳过可能意味着数小时的错误方向工作。\n\n这条规则在三个层面执行：SKILL.md本身、每个工作流的强制前置步骤、以及嵌入在所有薄包装中的重新阅读触发器（最后手段）。\n\n## 经验捕获与自我维护\n\n框架内置了事后审查（After-Action Review）机制，带有记录阈值。当调试时间超过预设阈值（如30分钟）时，必须将解决方案记录到references/gotchas.md。\n\n此外，框架还定义了健康检查、拆分/合并程序和弃用工作流，确保文档保持精简。定期运行健康检查可以发现过时的规则、重复的内容和未使用的文件。\n\n## 跨平台兼容性\n\nSkill-Based Architecture的一个显著优势是其跨平台兼容性。生成的技能结构兼容：\n\n- Cursor（.cursor/rules/.mdc）\n- Claude Code（CLAUDE.md、.claude/）\n- Codex（.codex/）\n- Windsurf\n- OpenClaw\n\n这意味着项目团队不需要为每个AI工具维护不同的文档集。一套skill-based架构，到处可用。\n\n## 与相关项目的对比\n\nSkill-Based Architecture与revfactory/harness等项目有相似之处，但定位不同：\n\n| 特性 | harness-architect | revfactory/harness |\n|------|-------------------|-------------------|\n| 范围 | 完整工具（设置/规则/代理/剧本/钩子/MCP） | 代理/技能团队中心 |\n| 输入 | 项目路径扫描 + 交互式访谈 | 用户叙述式请求 |\n| 工作流 | 9阶段编排 + 阶段门 + 恢复 | 单一会话6阶段 |\n| 设计审查 | 红队顾问（每阶段独立批评） | 无内置 |\n| 核心模式 | 代理-剧本分离（WHO/HOW）、纯编排器 | 用户主导设计 |\n\n简而言之：revfactory/harness适合快速创建代理/技能团队，harness-architect适合构建可恢复、可验证的完整工具。\n\n## 使用场景\n\nSkill-Based Architecture特别适合以下场景：\n\n大型代码库：项目规模庞大，规则复杂，需要结构化组织才能有效使用AI代理。\n\n多代理协作：多个AI代理参与同一项目，需要统一的知识来源确保一致性。\n\n知识传承：团队希望将隐性知识（调试技巧、架构决策、常见陷阱）转化为显性文档。\n\n工具迁移：在不同AI工具之间切换时，保持项目规则的一致性。\n\n长期维护：项目需要持续演进，文档需要与代码同步更新。\n\n## 实施建议\n\n要开始使用Skill-Based Architecture，建议遵循以下步骤：\n\n1. 审计现有文档：识别当前文档中的问题——重复、过时、分散、过于庞大。\n\n2. 定义技能边界：确定技能的范围和激活条件。一个好的技能应该专注于特定领域（如API测试、前端开发、数据库迁移）。\n\n3. 迁移到标准结构：将现有文档重组为SKILL.md、rules/、workflows/、references/的结构。\n\n4. 编写薄包装：为每个支持的AI工具创建入口文件，指向核心技能。\n\n5. 建立维护流程：设置定期健康检查，定义何时记录新经验，何时弃用旧规则。\n\n6. 迭代优化：根据实际使用情况调整结构，可能需要进行多次拆分或合并。\n\n## 局限与注意事项\n\nSkill-Based Architecture并非银弹。它主要解决上下文层问题，但不涵盖：\n\n- 工具执行恢复\n- 长链检查点/恢复\n- 多代理编排\n\n这些是项目特定的工程问题，必须存在于每个项目自己的rules/或workflows/中，而非元技能的模板里。\n\n此外，框架的有效性依赖于团队的执行纪律。如果开发者不遵循重新阅读规则，不记录调试经验，不运行健康检查，文档质量会迅速退化。\n\n## 结语\n\nSkill-Based Architecture代表了AI辅助开发领域的一个重要进化：从"给AI一堆文档让它自己理解"到"结构化地组织知识让AI高效使用"。它承认了一个基本事实：在大型项目中，上下文管理是AI代理效能的瓶颈。\n\n通过最小化token浪费、消除规则重复、按任务路由、自动捕获经验、自我维护，Skill-Based Architecture为AI代理提供了一个可持续演进的上下文层。对于正在使用AI代理进行严肃软件开发的团队，这是一个值得认真考虑的框架。\n\n正如项目文档所言："你得到的不仅仅是一个更整洁的文档文件夹——而是最理解你项目的技能。"在AI与人类开发者协作的未来，这种结构化的知识管理将成为高效团队的标配。

Skill-Based Architecture：为AI代理构建项目专属技能的知识蒸馏框架\n\nAI代理文档化的困境\n\n随着Cursor、Claude Code、Codex、Windsurf等AI编程代理的普及，项目文档不再只是给人类开发者阅读的材料——它们成为了AI代理理解项目规则、遵循编码规范、执行复杂工作流的关键输入。然而，传统的文档组织方式在面对AI代理时暴露出了严重的问题。\n\nSkill-Based Architecture项目敏锐地识别了这些痛点：\n\n单一巨型文件问题。许多项目将所有规则塞进一个400多行的SKILL.md文件，导致代理在每次任务时都要读取全部内容，既浪费token又拖慢响应速度，维护起来也极其困难。\n\n规则分散与冲突。规则散落在AGENTS.md、.cursor/rules/、CLAUDE.md等多个位置，造成内容重复、规则矛盾，代理无法确定应该遵循哪个版本。\n\n只增不减的文档堆积。有用的规则被过时的内容淹没，代理无法辨别哪些规则仍然有效。\n\n被动描述vs主动触发。技能描述往往是静态摘要而非明确的激活条件，导致代理无法自动判断何时应该使用该技能。\n\n宝贵经验流失。调试过程中花费30分钟以上才解决的棘手问题，其解决方案往往被埋没在文档深处，无法在类似任务中自动浮现。\n\n缺乏事后复盘。工作中发现的教训没有被记录，同样的错误反复发生。\n\n叙事化而非结构化。经验教训以故事形式书写，而非可复用、可转移的结构化知识。\n\nSkill-Based Architecture正是为解决这些问题而设计的元技能框架。\n\n核心理念：输出即目的\n\nSkill-Based Architecture的核心理念可以用一句话概括："输出即目的"。它不仅仅是为了让文档更整洁，而是要生成一个真正理解项目的技能——这个技能具备路由能力、自我维护能力、经验捕获能力，并且能在任务匹配时自动触发。\n\n框架的工作流程非常直观：将你的项目指向skill-based-architecture，它会分析代码库，将项目的规则、工作流和宝贵经验蒸馏到一个专用的skills//目录中。生成的技能成为所有AI代理（Cursor、Claude Code、Codex、Windsurf、Gemini等）在执行任务前咨询的单一事实来源。\n\n三层可靠性模型\n\nSkill-Based Architecture明确了自己的定位：它解决的是AI代理可靠性的"上下文层"问题，而非全部问题。项目将代理可靠性分为三个层次：\n\n| 层次 | 解决的问题 | 本技能提供的支持 |\n|------|-----------|----------------| \n| 提示（Prompt） | 如何表述任务 | 间接——通过描述作为触发条件 |\n| 上下文（Context） | 如何向模型传递信息 | 主要关注点——路由、必读文件、薄包装、渐进式披露 |\n| 工具（Harness） | 周围系统如何保持执行稳定 | 部分——会话纪律+合理化表格+可选SessionStart钩子 = 最小化工具，用于长会话中的上下文重新注入 |\n\n当代理表现不稳定时，根本原因很少是模型本身。项目建议运行四原语审计：系统是否有状态跟踪、节点级验证、带检查点的编排、恢复路径？三个"否"意味着是工具问题而非模型问题。重新调整提示无法弥补缺失的工具。\n\n目录结构规范\n\nSkill-Based Architecture定义了一套清晰的目录结构：\n\n\nskills/<name>/\n├── SKILL.md <=100行：必读列表 + 任务路由表\n├── rules/ 长期约束（什么始终为真）\n├── workflows/ 分步程序（如何做某事）\n├── references/ 背景：架构、陷阱、索引\n│ └── gotchas.md 已知陷阱——往往是最有价值的内容\n└── docs/ 可选：提示、报告、外部文档\n\n\n根入口文件（AGENTS.md、CLAUDE.md、CODEX.md、.cursor/rules/.mdc、.codex/）变成"薄包装"——每个不超过15行，只包含路由表和指向正式技能的指针。\n\n双层阅读系统\n\nSKILL.md采用双层阅读系统，而非一次性加载所有文档：\n\n必读（Always Read）：2-3个文件，约150行，每个任务都必须加载。这通常包括rules/project-rules.md和rules/coding-standards.md。\n\n常见任务（Common Tasks）：按任务路由，代理只读取当前任务列出的文件。例如：\n\n| 任务 | 需要读取的文件 | 工作流 |\n|------|---------------|--------|\n| 修复bug | rules/project-rules.md + rules/coding-standards.md | workflows/fix-bug.md |\n| 添加功能 | rules/-rules.md | workflows/.md |\n\n每个入口文件嵌入路由表——不仅仅是"去读取SKILL.md"。这种设计在长对话中能够经受上下文摘要的考验，而自然语言指令往往会丢失。\n\n描述作为触发条件\n\n传统技能描述往往是被动摘要，如"帮助API测试"。Skill-Based Architecture要求描述成为明确的激活条件：\n\nyaml\n不好的描述——技能永远不会触发\ndescription: 帮助API测试\n\n好的描述——可靠激活\ndescription: >\n 当用户要求\"测试API端点\"、\"为REST API编写集成测试\"\n 或\"调试失败的HTTP请求\"时使用此技能。\n 当任务涉及HTTP状态码、请求/响应负载或API认证流程时激活。\n\n\n这种显式的触发条件让代理能够可靠地判断何时应该加载该技能。\n\n会话纪律与重新阅读规则\n\nSkill-Based Architecture强制执行严格的会话纪律：\n\n每个新任务——即使是同一会话中的第二个或第三个任务——必须重新阅读SKILL.md，重新匹配常见任务路由表，并重新读取该路由列出的所有文件。\n\n"我之前已经读过了"不是有效理由。上下文会被静默压缩；新任务可能匹配不同的路由；部分记忆比没有记忆更糟糕。重新阅读只需几秒钟，跳过可能意味着数小时的错误方向工作。\n\n这条规则在三个层面执行：SKILL.md本身、每个工作流的强制前置步骤、以及嵌入在所有薄包装中的重新阅读触发器（最后手段）。\n\n经验捕获与自我维护\n\n框架内置了事后审查（After-Action Review）机制，带有记录阈值。当调试时间超过预设阈值（如30分钟）时，必须将解决方案记录到references/gotchas.md。\n\n此外，框架还定义了健康检查、拆分/合并程序和弃用工作流，确保文档保持精简。定期运行健康检查可以发现过时的规则、重复的内容和未使用的文件。\n\n跨平台兼容性\n\nSkill-Based Architecture的一个显著优势是其跨平台兼容性。生成的技能结构兼容：\n\n- Cursor（.cursor/rules/.mdc）\n- Claude Code（CLAUDE.md、.claude/）\n- Codex（.codex/）\n- Windsurf\n- OpenClaw\n\n这意味着项目团队不需要为每个AI工具维护不同的文档集。一套skill-based架构，到处可用。\n\n与相关项目的对比\n\nSkill-Based Architecture与revfactory/harness等项目有相似之处，但定位不同：\n\n| 特性 | harness-architect | revfactory/harness |\n|------|-------------------|-------------------|\n| 范围 | 完整工具（设置/规则/代理/剧本/钩子/MCP） | 代理/技能团队中心 |\n| 输入 | 项目路径扫描 + 交互式访谈 | 用户叙述式请求 |\n| 工作流 | 9阶段编排 + 阶段门 + 恢复 | 单一会话6阶段 |\n| 设计审查 | 红队顾问（每阶段独立批评） | 无内置 |\n| 核心模式 | 代理-剧本分离（WHO/HOW）、纯编排器 | 用户主导设计 |\n\n简而言之：revfactory/harness适合快速创建代理/技能团队，harness-architect适合构建可恢复、可验证的完整工具。\n\n使用场景\n\nSkill-Based Architecture特别适合以下场景：\n\n大型代码库：项目规模庞大，规则复杂，需要结构化组织才能有效使用AI代理。\n\n多代理协作：多个AI代理参与同一项目，需要统一的知识来源确保一致性。\n\n知识传承：团队希望将隐性知识（调试技巧、架构决策、常见陷阱）转化为显性文档。\n\n工具迁移：在不同AI工具之间切换时，保持项目规则的一致性。\n\n长期维护：项目需要持续演进，文档需要与代码同步更新。\n\n实施建议\n\n要开始使用Skill-Based Architecture，建议遵循以下步骤：\n\n1. 审计现有文档：识别当前文档中的问题——重复、过时、分散、过于庞大。\n\n2. 定义技能边界：确定技能的范围和激活条件。一个好的技能应该专注于特定领域（如API测试、前端开发、数据库迁移）。\n\n3. 迁移到标准结构：将现有文档重组为SKILL.md、rules/、workflows/、references/的结构。\n\n4. 编写薄包装：为每个支持的AI工具创建入口文件，指向核心技能。\n\n5. 建立维护流程：设置定期健康检查，定义何时记录新经验，何时弃用旧规则。\n\n6. 迭代优化：根据实际使用情况调整结构，可能需要进行多次拆分或合并。\n\n局限与注意事项\n\nSkill-Based Architecture并非银弹。它主要解决上下文层问题，但不涵盖：\n\n- 工具执行恢复\n- 长链检查点/恢复\n- 多代理编排\n\n这些是项目特定的工程问题，必须存在于每个项目自己的rules/或workflows/中，而非元技能的模板里。\n\n此外，框架的有效性依赖于团队的执行纪律。如果开发者不遵循重新阅读规则，不记录调试经验，不运行健康检查，文档质量会迅速退化。\n\n结语\n\nSkill-Based Architecture代表了AI辅助开发领域的一个重要进化：从"给AI一堆文档让它自己理解"到"结构化地组织知识让AI高效使用"。它承认了一个基本事实：在大型项目中，上下文管理是AI代理效能的瓶颈。\n\n通过最小化token浪费、消除规则重复、按任务路由、自动捕获经验、自我维护，Skill-Based Architecture为AI代理提供了一个可持续演进的上下文层。对于正在使用AI代理进行严肃软件开发的团队，这是一个值得认真考虑的框架。\n\n正如项目文档所言："你得到的不仅仅是一个更整洁的文档文件夹——而是最理解你项目的技能。"在AI与人类开发者协作的未来，这种结构化的知识管理将成为高效团队的标配。