Reference · 综合 · 横跨 22 个已发布 skill

本地 md 文件全景速查

每个本地 Markdown 文件的创建者、创建时机、修改时机，一页打尽。完整教学见 Lesson 0022； 权威出处：issue-tracker-local.md、 setup/SKILL.md、 domain-modeling/SKILL.md。

四层 + 仓库之外

配置层 setup 写一次 → CLAUDE.md/AGENTS.md「## Agent skills」区块 · docs/agents/{issue-tracker,domain,triage-labels}.md 领域层 懒创建+内联更新 → CONTEXT.md · CONTEXT-MAP.md · docs/adr/NNNN-*.md 产物层 仅本地 tracker → .scratch/<feature>/spec.md · .scratch/**/issues/NN-*.md · .scratch/<effort>/map.md · .out-of-scope/<concept>.md 教学层 teach 工作区 → MISSION.md · RESOURCES.md · NOTES.md · GLOSSARY.md · learning-records/NNNN-*.md 仓库外 OS 临时目录 → handoff 交接 md · improve-codebase-architecture 的 HTML 报告

完整地图（文件 × 创建 × 修改）

文件 创建者 × 时机 修改者 × 时机
CLAUDE.md/AGENTS.md 的 ## Agent skills 区块 setup 第四步，编辑已存在者（都没有才问建哪个）；已有区块原地更新 重跑 setup；用户手改
docs/agents/issue-tracker.md setup 第四步，必写（种子模板复制） 用户手改（如 PR 旗标）；重跑 setup
docs/agents/domain.md setup 第四步，必写（单/多上下文布局） 重跑 setup
docs/agents/triage-labels.md setup 第四步，仅当装了 triage 用户手改标签映射
CONTEXT.md（根或 src/<ctx>/） domain-modeling 懒创建：第一个术语解决时（setup 不建） domain-modeling 内联更新（入口：grill-with-docs / triage 第四步 / improve-codebase-architecture / wayfinder）；手改安全
CONTEXT-MAP.md 无明确创建者（文档空白）；多上下文布局下手动补建，格式见 CONTEXT-FORMAT.md 新增上下文时更新
docs/adr/NNNN-*.md domain-modeling 懒创建：难逆转+出人意料+真实取舍三者同满足；improve-codebase-architecture 在有分量的拒绝时提议 旧文件不改；被推翻时新写一份标 Status 取代
.scratch/<feature>/spec.md＊ to-spec 第三步「发布到 tracker」时，含 Status: ready-for-agent 无——写一次即冻结
.scratch/<feature>/issues/NN-*.md＊ to-tickets 第五步，一单一文件，从 01 按依赖序编号 triage 改 Status 行 + 追加 ## Comments 简报；prototype 追加原型分支指针
.scratch/<effort>/map.md＊ wayfinder「画地图」第三步 wayfinder：工单解决后往「已做决定」追加指针；雾散/越界/翻案时同步改
.scratch/<effort>/issues/NN-*.md＊ wayfinder：画地图一批 + 探路中新问题逐张增 wayfinder：认领 → Status: claimed；解决 → 写 ## Answer + resolved
.out-of-scope/<concept>.md triage：enhancement 被判 wontfix 时（已实现而关的不写） triage：同概念再被提时追加历史行；维护者翻案时整文件删除
research 结论 md（路径随仓库惯例） research 后台 agent，调研结束时 无
handoff 交接 md（OS 临时目录） handoff，每次手动调用 无——下个会话的消耗品
prototype 的 README.md（可选） prototype LOGIC 分支需说明运行方式时 无——随原型一起删
MISSION.md teach 首次会话问清动机后 目标转移时（需用户同意 + 配学习记录）
RESOURCES.md / NOTES.md / GLOSSARY.md teach：早期 / 首个偏好 / 首个术语（均懒创建） teach 持续维护，就地更新
learning-records/NNNN-*.md teach：四类学习事件（真理解/已有知识/纠正误解/目标转移） 不可变；被推翻标 Status: superseded，不删除

＊ = 仅 local markdown tracker 模式；远端 tracker（GitHub/GitLab）下这些全部是远端 issue/评论/标签，本地不落文件。

沉默名单（不写 md 的 10 个 skill）

grill-me · grilling · ask-matt · implement · tdd · diagnosing-bugs · code-review · resolving-merge-conflicts · codebase-design · writing-great-skills。 （12 写 + 10 不写 = 22，与 plugin.json 的已发布集合对平。）

三个坑