用途:为代码库建立分层的 Intent Layer,即通过 AGENTS.md 文件为 AI 智能体提供上下文,使其能像资深工程师一样导航代码库。适用于初始化新项目,或为已有仓库添加上下文基础设施。
核心原则:项目根目录只保留一个上下文文件,CLAUDE.md 与 AGENTS.md 不应在根目录共存;复杂子系统可在子目录中创建子级 AGENTS.md。
工作流:
- 检测状态:scripts/detect_state.sh /path/to/project,返回 none、partial 或 complete。
- 路由:none/partial 进入初始设置;complete 进入维护模式。
- 测量:先展示表格,运行 scripts/analyze_structure.sh /path/to/project 与 scripts/estimate_tokens.sh /path/to/each/source/dir。
- 决策:无根文件时询问使用 CLAUDE.md 还是 AGENTS.md;已有根文件时添加 Intent Layer 章节,必要时增加子节点。
- 执行:参考 references/templates.md 的结构与 references/node-examples.md 的真实模式;校验规则为一个根文件、READ-FIRST 指令、每个节点少于 4k tokens。
维护模式(状态为 complete 时)询问用户:a) 审计节点,使用 references/capture-protocol.md 的 SME 问题;b) 查找候选节点,重新测量 tokens 并建议新节点;c) 两者都做。
创建子节点的信号:目录超过 20k tokens、职责转移、隐藏契约或不变量、横切关注点(放在最近公共祖先)。不要为每个目录、简单工具或测试文件夹(除非复杂)创建。
记录现有代码时可询问:该区域负责什么、范围外是什么;哪些不变量绝不能违反;什么反复让新工程师困惑;应始终遵循哪些模式。
资源:脚本 detect_state.sh、analyze_structure.sh、estimate_tokens.sh;参考 templates.md、node-examples.md、capture-protocol.md。该技能源自 crafter-station/skills(MIT),由 Railly Hugo 为 Crafter Station 构建,基于 Tyler Brandt 的 The Intent Layer。