面向智能体的文档入口¶
本目录是 Skill Family Foundation 给智能体（Agent）用的决策入口。人类读者从根 README.md 进入；智能体在有限上下文里先读这里，再按意图跳到具体能力，避免通读全部源码。
Foundation 不拥有业务语义。它只提供三件事：机器契约（Contracts）、Node 薄机制运行时（Harness）、工程阶段的四个命令（Engineering Kit），以及横向声明差异的 Profile。领域状态机、模型编排、发布远端写入、审计语义都留在调用方或其他项目。
阅读顺序¶
智能体按下面的顺序取用，不必从头读到尾：
capability-catalog.json—— 全部稳定与 candidate 能力的机器事实目录，是判断「该需求是否属于 Foundation、落在哪一层、用哪个入口」的起点。architecture-routing.md—— 从架构意图到层/能力/入口/外部项目的决策表与决策树。capability-catalog.schema.json—— 目录自身的结构合同，校验器与投影都依赖它。- 根
README.md的 Agent Quick Reference —— 只做路由，不复制 API。 - 三个包 README 的 Agent Quick Reference —— 精确到包级能力和失败边界。
../reference/failure-and-side-effect-matrix.md—— 每个公共入口的读写/spawn/Git/网络/残余状态/错误码。../reference/api/README.md—— 三包公共 API 的人类可读投影，按入口给出签名、输入/输出、纯函数性、副作用、稳定错误码与details.kind、前置与信任锚、since/stability、源文件与正例/负例测试、调用方仍拥有的业务语义；与 catalog 能力 ID 互链。
事实优先级：本文档只消费机器真源（package.json、src/index.mjs、CLI、registry.json、profile descriptor）。版本、命令、包数、支持状态都从真源复算，不从记忆或旧文档照搬。
目录合同¶
docs/agents/ 下的文件承担不同职责，不互相重复：
| 文件 | 角色 | 谁该改 |
|---|---|---|
capability-catalog.json |
机器可读的能力事实，文档层唯一事实面 | 能力变化时改，并经 capability-catalog-check.mjs 校验 |
capability-catalog.schema.json |
目录结构合同 | 结构变化时才改 |
architecture-routing.md |
意图 → 层/能力/入口/外部项目的决策 | 路由裁决变化时改 |
README.md（本文件） |
智能体总入口与阅读顺序 | 入口结构变化时改 |
../reference/api/README.md 及三包页 |
公共 API 的人类可读投影，catalog 能力的签名级展开 | 真实导出变化时改，并与 capability-catalog-check.mjs 同步 |
capability catalog 不是 Contracts 的新公共对象，也不是第四类登记表。它只是文档层的机器事实，避免 README 形成第二套会漂移的手写权威。
架构设计工作法¶
智能体处理一个 Foundation 相关需求时，按下面四步推进：
- 先判归属。该需求是否含领域语义、业务状态机或审计 oracle？若是，留在消费者，只把业务中立机制接 Foundation。
- 再判分层。结构/协议/稳定错误码/对象 Schema 落 Contracts；跨技能族可复用的 Node 机制落 Harness；scaffold/adopt/projection/check 或具体 Profile 注入落 Kit/Profile。
- 查目录定入口。在
capability-catalog.json按layer与intent找到能力，读它的entrypoints、sideEffects、failureSemantics、ownedByCaller、routeElsewhere。 - 验证据再下结论。目录每条能力都带
sourceRefs与positiveTestRefs/negativeTestRefs，改动判断前先回到这些真源确认，不凭目录散文推断。
路由边界的硬规则：Foundation 不拥有远端写入（归 release-skill）、不拥有任务/重试/返工（归 loop-agent）、不拥有制品关系与 context（归 artifact-graph）、不拥有领域审计语义（归独立审计消费者）。详情见
architecture-routing.md的路由表。
candidate 项的 entrypoints 始终给出规范入口。若同时存在 legacyEntrypoints，表示这是 0.10.0 以前形成的历史债务，
消费者需迁移一次；迁移后仅晋升 stable 不再改合同身份。消费者仍需更新精确 pin 才能取得新发布的 stable 承诺。
0.10.0 以后新 candidate 的能力 ID、入口、Schema $id 与 operation 都不得编码成熟度。
与机械门禁的关系¶
两个检查脚本守护目录与 README 不漂移：
scripts/docs/capability-catalog-check.mjs校验结构、唯一 ID、源/测试引用存在、unsupported 边界、Kit 四命令未扩张。scripts/docs/agent-section-check.mjs校验根 README 与三个包 README 的固定 Agent Quick Reference 章节、必含子标题与能力 ID 链接。
二者都只报形状不自动改文；警告项需回到真源与声音人工判断。