skill-based-architecture

基于 Skill 的架构

将过于庞大的单文件 Skill 或分散的项目规则重构为组织良好的 Skill 目录。基于官方的最简 Agent Skill 契约（name + description），并在一个简短的 SKILL.md 不再够用时启用。

适用场景

• 单个 SKILL.md 超过约 150 行，混杂规则、工作流和背景资料；或项目规则分散在 AGENTS.md、CLAUDE.md、CODEX.md、.cursor/rules/、.claude/ 等位置。
• 经常性任务需要流程、适配的验证或可靠的完成检查；或用户明确要求采用基于 Skill 的架构或整合规则。
• 临时仓库无需持久的路由机制、团队已有可用的精简指令系统，以及小型项目均可跳过；但即使在这些情况下，明确提出的 SBA 请求仍可能生成完整、直接承载内容的 SKILL.md。

渐进式严谨度

只在遇到实际需求时扩展。物化器会根据目标证据在内部推导出单文件、轻量目录或完整/广泛结构；用户不能选择层级、配置、能力包或安装模式。routing.yaml、任务执行、任务收尾、维护检查以及每个运行环境的适配层都需要各自具备路由、加载或归属方面的实际需求。当内容将不变的设计理论与当前代码事实混杂在一起时，按抽象层次拆分（骨架/肉）：抽象理论 → architecture/，代码映射 → references/，项目惯例 → conventions/，各模块的特定陷阱 → gotchas/（方法论仍放在 rules/）。内容缩减时也应降级结构。详情请见：references/progressive-rigor.md。

按证据选择结构

# direct
skills/<name>/SKILL.md
# folder-light or broad: only admitted owners/directories
skills/<name>/{SKILL.md,rules/,workflows/,references/,scripts/}

仅当路由数据有独立归属方时才添加 routing.yaml；仅为已证实的使用者提供根目录入口、工具入口和注册位置。保留现有根目录入口。生成的、带路由的入口使用 routing.yaml 引导；直接入口则指向唯一的 SKILL.md 流程。仅当检测到 Cursor、已声明使用 Cursor、当前正在使用 Cursor 或用户明确要求时，才进行 Cursor 注册。来源请见 REFERENCE.md。

核心原则

1. 单条精简入口 — SKILL.md 采用双重预算：描述 ≤ 25 行（触发短语 + 激活）+ 正文 ≤ 90 行（导航）；它负责导航，而非详尽罗列。✓ 检查：冒烟测试分别报告两项；任一超限 → 拆分意图簇／将细节移至子文件。
2. 纳入文件夹时只用一个技能文件夹 — 轻量文件夹和广泛结果都将正式文档置于 skills/<name>/ 下；直接结果可以保留为完整的单个 SKILL.md 载体。✓ 检查：生成的根目录入口中，没有任何一个成为第二个规则／工作流的所有者。
3. 规则 ≠ 流程 — rules/ 用于约束，workflows/ 用于程序。✓ 检查：rules/ 中出现任何编号步骤，或 workflows/ 中出现“始终／绝不”，都表示混用。
4. 纳入时以 routing.yaml 为准 — 直接载体在 SKILL.md 中拥有唯一的路由；多个／共享路由仅存放于 routing.yaml 中，并据此生成路由外壳。✓ 检查：是否存在足以证明清单合理性的独立选择器或使用方？它适配的同步检查是否通过？
5. Harness 表面应贴合读者 — 仅创建／合并现有文件／配置、当前 Harness、仓库／团队声明或明确请求所支持的条目和注册项。✓ 检查：每个生成的表面都能指出其读者吗？每个现有条目都得到保留了吗？
6. 渐进式严谨 — 三种载体（单文件／轻量文件夹／完整）只在有需要时逐步扩展，不是供用户选择的打包方案。✓ 检查：你能说出迫使每个生成文件出现的独立职责吗？
7. 描述 = 粗粒度激活 — 领域边界 + 真实的用户触发短语；绝不枚举工作流关键词，也不总结工作流步骤。✓ 检查：修改 routing.yaml 中的任务路由时，无需重写描述吗？描述／标签中是否没有包含 Agent 无需打开正文就能照着执行的 HOW 内容？
8. 易错点最有价值 — 主动维护代价高昂的陷阱；确保它们易于发现。✓ 检查：每个高代价易错点是否都由纳入的路由所有者（SKILL.md 或 routing.yaml）激活，而不是只埋在 references/ 中？
9. 渐进式披露 — 每个加载的文件都需要有独立的任务时理由；条件性内容应移出启动读取集；每个真实调用方都会共同加载的文件应合并，除非所有权／生成机制要求分开存储。✓ 检查：对于每次路由读取，你能否指出一个此刻需要它的请求，以及它会改变的下一步操作？不能 → 条件路由、合并或移除。
10. 任务执行 + 收尾 — 只有一个明确的只读或固定契约维护操作，且不引入新的预期行为时，才直接执行；任何新增或更改用户可见行为、业务流程／状态或外部契约的操作，都应遵循 requirement-ready -> Task Anchor -> implementation-ready -> Native Plan -> mutation；按比例呈现对齐情况，并在每个主要步骤前运行精简的 Anchor Checkpoint。工作流是领域程序；Native Plan 仅是本 Session 的运行时步骤所有者，不持久化规划文件。完整协议：references/protocols.md § Task Execution Protocol。
11. 持久记录规则 — 通用记录应适用于多个项目；业务全局模型应保持项目专属，但必须在实现被替换后仍然有效。✓ 检查：使用目标对应的测试——跨项目模式或跨实现的业务事实——不要将代码细节混入其中（参考）。
12. 自我维护 — 行数是评估信号，不代表自动执行操作；仅当任务可独立选择时才拆分；普遍共同加载／共同变更的文件应合并，除非所有权或生成机制能说明这一边界。✓ 检查：前后加载矩阵能否证明无关读取减少，同时不丢失定义、条件、边界或理由？
13. 激活优先于存储 — 仅将内容放在 references/ 中不算“已捕获”；它必须位于任务路径上，且读取后会改变 Agent 的行为；已触达但不起作用（内容正确、位于路径上，但 Agent 的后续行动完全相同）是另一种失败，任何结构门槛都无法发现，只有判断才能识别。✓ 检查：追踪正常路径——触达该入口是否会改变下一步操作（读取文件、运行检查、跳过步骤）？
14. Token 效率 — Always Read 默认为空；每次新增都必须证明，在选择工作流之前，所有真实任务都需要它；只有当证据或阶段边界能够改变下一步操作时，才加载领域知识和生命周期知识。✓ 检查：是否可以推迟任何启动读取，而不改变首次工作流决策？如果可以，将其移至该工作流检查点。
15. 合理化借口表 — 仅逐字记录真实压力测试失败中出现的借口。✓ 检查：每一行都能追溯到真实失败吗？若未观察到失败且不愿意建立基线 → 属于想象出来的痛点，删除（拒绝的合理化借口，第 9 阶段）。
16. 响应规范 — 输出简短、准确、直接的回答；避免叙述流程、自我表扬、无谓确认和复述需求。✓ 检查：每句话都服务于明确请求吗？不是 → 删除。
17. 不同证明主张应分开 — 适配的结构检查、来源处置迁移证据和 Agent 实时行为证明的是不同方面；结构检查通过不能被当作语义或行为正确性的证明。✓ 检查：最终主张是否指出实际运行的确切层级，并将无法获取的实时证据报告为无结论？

常见陷阱

1. 缺少已证明可用的 harness 承载面——项目证明了 Cursor/Claude 等读取器可用，但缺少与之匹配的注册项/入口 → 该 harness 永远无法发现正式归属者；相反的错误（未经证据就输出所有 harness）则会带来永久维护成本。
2. 路由载体错误——路由 shell 只说“去读 SKILL.md”，却没有生成的 routing.yaml 引导文件；或者直接项目仅为保持一致而添加了空清单 → 两种情况都会导致恢复流程中断，或出现虚假机制。
3. 描述含糊或范围错误——语态被动、语言错误、范围太窄（仅“修复 bug”），或塞入所有工作流关键词，导致无法匹配自然语言请求或触发过于频繁；描述应保持在领域层面，并在 SKILL.md 中路由任务。
4. 已记录但未激活，或已激活但不起作用——代价高昂的陷阱记录在 references/ 中，却未出现在所属工作流检查点；或者虽然在路由路径上，却只是作为背景事实写入，从不改变 Agent 的下一步行动；可访问 ≠ 有用。
5. 物化过程中丢失完成责任——主要工作完成后，Agent 就认为自己已结束，尽管已证明可用的工作流/Closure 归属者要求进行匹配的验证或 AAR；简单工作流可以在流程中直接承担这一责任；纯问答/只读任务仍可豁免。
6. 项目专属记录——以项目叙事形式编写的经验教训（“在我们的产品模块中，我们发现……”）在当前上下文之外毫无用处；记录前先应用泛化规则。
7. 长会话缺少 SessionStart hook——/clear 或 /compact 会悄无声息地将 SKILL.md 从上下文中移除，用户却毫无察觉 → 如果你的 harness 支持，请安装 SessionStart hook（references/thin-shells.md § SessionStart Hook）。
8. 多任务会话中跳过路由——Agent 将上一个任务的路由复用于新任务，并依据过时记忆开展工作，错过关键规则 → 每个任务都要重新匹配路由（分层会话规范；所有 shell 都携带触发条件）。
9. 缺少或流于形式的 Task Anchor / 长任务偏移——Agent 开始非 Simple 任务时没有稳定的 Goal/Done When，或者输出一个与原生 Plan 重复的带标签区块 → 使用 templates/skill/workflows/task-execution.md；将 Anchor 保留为运行时状态，并在最终验证/提交前运行 reboot-check.md。
10. 臆想式痛点工程——添加任何机制（规则/脚本/文件/模板章节）之前，先给出具体场景（文件+行号 / 提交 / 会话）证明问题确实发生过；没有 → 不要添加。历史记录：5 个幽灵脚本（2026-05-19 移除）、dossier schema（2026-05-19 移除）、优先反思的模式转变（2026-05-20 放弃）、观察日志（2026-05-20 否决）。

内容分类

内容类型——按抽象层级划分：骨架（架构/工作流/规则 = 不变理论）vs 肉（约定/陷阱/参考 = 当前代码事实）· 拆分指南	目标位置	类型
抽象设计理论——分层/契约/编排/事务原则，以及“为什么”（不是模块地图）	architecture/	骨架
代码地图 + 背景——模块树、目录布局、源代码索引、构建/环境说明	references/	肉
代码风格——命名、路径、命令、格式、必须/禁止约定	conventions/	肉
与代码耦合的隐患（症状 → 原因 → 修复），仅按可独立路由的模块拆分	gotchas/（仅在多文件压力下才选择 gotchas/index.md）	肉
逐步任务流程（流程理论）	workflows/	骨架
提示词/报告/文档 · 编辑器配置（薄 shell）	docs/ · .cursor/ .claude/	—

多技能与组合

多技能仓库——请参阅 references/multi-skill-routing.md（运行 + 拆分 + 共存）。关于如何在工作流中调用其他技能（嵌入式 / 串行 / 子 Agent 委派），请参阅 references/skill-composition.md 和入门模板 templates/skill/workflows/invoke-skill.md.example。

资源

• WORKFLOW.md——迁移流程（快速入门 + 9 个阶段 + 下游升级）
• REFERENCE.md + references/——模板、决策指南、反模式、故障排查、自托管路由源
• TEMPLATES-GUIDE.md——入门模板 + 元工作流模板；EXAMPLES.md + examples/——行为失败 + 前后对比场景