project-forge
Skill1 starsChanged 5 days agoMITView on GitHub
把一个项目目录锻造为规范项目：版本管理、远端仓库、文档套装、发布通道一次配齐， 并给出配好之后每天怎么干活的协作协议（改动从哪来、谁审、谁能合、合并后怎么收尾）， 收尾时问你要不要把它留下的痕迹清干净。 触发词：弄版本管理、配 git、上仓库、建仓库、推到 GitHub、初始化项目、项目起步、 新项目配置、标准化项目、规范项目、整理项目、给项目弄好、写 AGENTS.md、写 README、 写贡献指南、配 LICENSE、配 CI、发到 npm、发布、交棒、把脚手架痕迹清干净、 收 issue、审 PR、能不能自动合并、多人一起开发怎么分工。 覆盖各种技术栈：Node、Python、Rust、Go、Java、纯文档目录，以及插件类项目与 skill 项目。 只读勘察先行，按事实判定该做与不该做；幂等、可重复执行；默认私有仓库。 不用于：只改代码写法、只回答概念问题，也不替项目选型或生成骨架。
2 other projects use a version of this.
Adopted by
Most recently taken up by
- Wamikmk/project-forgetheir own version, first seen Jun 24, 2026
- dominionthedev/skillstheir own version, first seen May 22, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- Wamikmk/project-forge★ 2same name
- dominionthedev/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- AGENTS.mdAGENTS.md
The file
Files
project-forge
把一个项目目录锻造成规范项目。给一个目录，自己勘察现状，自己判断该做哪几件事，然后 一次做到位。
本文件是索引：只写「去哪读、按什么顺序、哪条不能破」。判据、理由、反例一律在
references/——该读的必须读全文，不要凭本文件的摘要动手。
何时使用
用户提到下面任何一类需求时使用。触发不要求用户说出本 skill 的名字——按意图判断。
- 版本管理：弄版本管理、配 git、上仓库、建仓库、推到 GitHub；
- 文档套装：写 AGENTS.md、写 README、写贡献指南、配 LICENSE；
- 发布通道：发到 npm、发布、配 CI；
- 协作协议：收 issue、审 PR、能不能自动合并、合并后怎么收尾、多人一起开发时怎么分工；
- 交棒：把脚手架痕迹清干净、撤掉本 skill 留下的东西、这个项目以后不用这个 skill 了；
- 笼统说法：
初始化项目、项目起步、新项目配置、标准化项目、规范项目、整理项目、给项目弄好。
不必使用的情况：只改代码写法、只回答一个概念问题——都不涉及这几个能力面。只修一个 bug
通常也不用：那属于日常执行，按项目自己的契约与协作协议做即可；只有当这个 bug 牵出一件
需要长期跟踪、要跨会话接续的事时，才用到本 skill 的工作记录与协作判据。
意图里含「生成项目本身」（选技术栈、创建源码与配置文件）时，先让骨架就绪再走本流程，
理由见 references/survey.md 第一节「与项目脚手架的分工」。
用户说「继续」时，不要把「做到哪一步」交给回忆——状态有机器载体，读它们：
判据在 references/survey.md 第六节「接着上次做」。
默认范围：没说范围时，默认是「整个项目配齐」
这条决定做多少，与「做哪些事」是两回事（后者由 P2 判定表回答）。
| 用户怎么说的 | 你做什么 |
| 什么都没说（只丢来一个目录，或只说「用一下这个 skill」） | 全量：勘察整个项目 → 按事实把该配的全部配上 → 已有的融合进来，不推倒重来 → 缺的补齐 |
| 笼统一句「规范一下 / 整理一下 / 全部补完 / 该有的都配上」 | 同上，一样是全量 |
| 点名某一件事（「配个 CI」「弄下版本管理」「写个 README」） | 只做那件事，其余不碰：判定与报告照旧走，动手范围就是它 |
| 点名几件事 | 只做这几件 |
「全量」不等于「全做」：哪些该做仍由勘察出的事实决定（纯文档目录不该有发布流程， 已有的远端不重建）。全量是把该做的都做完、不漏，不是把清单上每条都执行一遍。
「融合进已有项目」是默认姿态：多数项目交到手里时已经有 git、有远端、有 README。 做法是「先读、再判断、只补缺的」——已有的文件先读后合并，永不覆盖，已有的结构是权威； 只有用户明确说「重写」时才整篇替换。
记下的范围要贯穿全程：它决定 P7 传不传 --scope，也决定汇报里说「全部配好」还是
「只做了这一件」。中途改口就跟着改，并在汇报里说明。
硬不变量（任何情况下都成立）
- 只读先行：勘察没有完成之前，不写任何文件。判断建立在事实上，不建立在猜测上。
- 幂等：同一件事重复执行结果相同。已存在的文件先读后合并，永不覆盖；内容冲突
时报告并停下，不擅自取舍。
一处例外：
AGENTS.md里由内核标记圈定的那段内容归templates/agents-kernel.md独占，注入即刷新——那是单一真相源的同步，不算覆盖用户的成果。标记之外照旧不动： 标着「这里要人写」的节保留既有内容，纯生成内容按当前项目事实重新求值（所以 P5 建好 远端之后要再跑一次）。用户若在标记区内写过东西，注入前脚本会提醒他这段会被覆盖。 - 密钥零入库：提交之前先扫描，按
references/version-control.md的密钥门控分情况 处置（未跟踪排除、已历史轮换、占位继续）。报告位置到行，给出处置建议。凭据只从运行 环境读取，绝不写进项目里的任何文件。 - 对外与破坏性动作一次对齐：建仓库、推送、发布、公开仓库、改写历史——动手前先给
一份清单让用户过目（清单内容见
references/remote-github.md建仓节表格）。 强制推送与改写已推送历史永不自动执行。 - 平台中立：不假设操作系统与 shell。不写死 PowerShell / bash / cmd，不写死路径
分隔符。不把非 ASCII 的正文经 shell 传递——Release 说明、Issue、提案、审查评论都算，
一律先写成 UTF-8 文件、再按文件提交。完整规则见
references/remote-github.md的 6.5 与references/collaboration.md第九节，此处不复述。 - 不写死取值：账号、路径、版本号、仓库地址一律现场读（见「取值从哪来」）。
- 文档分层：面向 AI 的文档（
AGENTS.md）写机制与判据，需要取值时写「从哪里取」； 面向人的文档（README/CONTRIBUTING）写具体、可复制的命令与地址。 - 单一入口：细节全在
references/与templates/里，本文件不复述它们。 - 先确认仓库边界：目录体量异常大、或里面还嵌着别的仓库时，先停下确认，不要把 整根纳入。
- 收尾必问：P8 交棒时必须问一次「要不要把本 skill 留下的痕迹清掉」。
不问就收工，等于把痕迹永久留在项目里，那不是交付。问不到人时不要自作主张拆掉
——把这条待确认项写进汇报，等人回来定。判据与拆除顺序见
references/handoff.md。 - 合并按「收不收得回来」分级：低档可自动合（门禁全绿 + 审查零阻塞 + 有回滚点），
中档合完要通知人，不可逆的那一档必须人合；弱化门禁的痕迹一票否决，外部提案一律
不自动合。分档清单与理由见
references/collaboration.md第五节——三档的边界在那里 定义，这里不抄。
取值从哪来
本文件与所有 reference 都不写死具体值。需要时从项目自身读：
| 需要什么 | 从哪里读 |
| 项目标识、版本、依赖、发布范围 | 项目的清单 / 元数据文件（存在哪个用哪个） |
| 远端地址、当前分支、提交署名 | 版本控制配置（远端列表、当前分支、署名） |
| 当前登录的账号与作用域 | 对应生态的账号查询命令 |
| 年份（许可证版权行） | 系统时间 |
| 项目的意图与约定 | 项目自己的说明文档与既有配置 |
项目是这些事实的唯一权威来源。读不到就说明这项事实还不存在——那就先建立它， 或者问用户，不要编一个。
能力矩阵：事实 → 做什么
输入是勘察产出的全部事实，不只是生态判定：中间几行由 ecosystem.kinds 决定（可以
命中多项，一个仓库里有多种生态时逐项分别处理；生态名单以勘察为准，新增生态时矩阵、
插件索引、勘察三处同步），末尾那几行由 git（远端指向谁）与 artifacts（有没有声明
不可发布）决定。逐行求值，不要只遍历 kinds——末尾那几行恰恰是安全相关的。
这张表算的是「该做哪几件事」，与项目是新是旧无关。 已经进过 git、已经有远端、已经 有文档的项目，同样按这张表走——区别只在每一步是「建立」还是「补齐」。
| 勘察到的事实 | 版本管理 | 文档套装 | 远端 | 发布 |
docs-only（纯文档 / 素材） | 做 | 做 | 做 | 不做 |
node | 做 | 做 | 做 | 视声明而定 |
python / rust / go / java / ruby / php / dotnet / cpp | 做 | 做 | 做 | 视声明而定 |
其他已识别生态（以勘察 kinds 为准） | 做 | 做 | 做 | 视声明而定（无专章时按通用判据，不硬塞已知类型） |
插件类：被宿主加载的扩展（dsh-plugin / vscode-extension / obsidian-plugin 等） | 做，产物按专章判据处理 | 做 | 做 | 可发布（见专章） |
skill：被宿主加载的能力目录 | 做 | 做 | 做 | 通常不发布（分发靠克隆或复制，远端即分发） |
unknown 或 unrecognized | 先问用户这是什么项目；用户说明后按他声明的生态对应行执行，并把该结论记作本次判定依据；问不到人时留空待定，不编生态 | 同左 | 同左 | 同左 |
环境无可用版本控制（git.available 为假） | 跳过（本地文件照常整理，提交推送等有 git 再做） | 做 | 跳过 | 按现状（需打标签的发布动作暂缓） |
git.isRepoRoot 为假（目录在别人的仓库里） | 停下：这些 git 事实属于外层仓库，先问清边界 | 同左 | 同左 | 同左 |
已有远端（git.remote 非空 且 是仓库根） | 只校验与补缺 | 补缺 | 不重建 | 按现状 |
git.role 为 contributor-fork（origin 与项目声明的源仓库不是同一处，或存在与 origin 不同的 upstream） | 做 | 做 | 只推自己分支 | 不发布 |
git.role 为 undetermined（远端存在但认不出指向谁） | 做 | 做 | 按贡献者走：拉分支、推自己分支、开改动请求 | 不发布 |
已声明不可发布（artifacts.private） | 做 | 做 | 做 | 不做 |
skill 这一类的判据、语义、发布取向与「与插件类的分野」，见
references/skill-project.md（P1 之后即读，见 G8）；git.isRepoRoot 为假这一条
优先于上面所有行——不管判出什么生态，只要目录不在自己的仓库根上，先解决边界问题。
多包仓库另有一行输入：workspace.declared 为真时，P4 的 AGENTS.md 按根与子包
分工写、P5 的 CI 在根层跑覆盖全部子包的那条命令；为假时不要去找子包，也不要写
「各子包分别……」这类句子。字段与判据见 references/survey.md 的 workspace 一节。
同一行里若有多列冲突，按更保守的那一列执行（例如既 docs-only 又已有远端：远端不
重建，发布仍不做）。发布这一列判「能不能发」的依据见 references/publish.md；不是所有
项目都该发布，「不发布」是正常结果，不是失败。
已经有基础的项目（最常见的情况）
真实场景里，交到手里的项目很少是白纸：多半已经进过 git、已经有远端、已经有一个
写得不太好的 AGENTS.md。这时每一件事都从「建立」变成「先看现状，再补缺口」——
核心纪律只有一条：先读，再判断，只补缺的。逐阶段的增量做法见
references/survey.md 第四节的状态判定表；散文文件的合并规则见 references/docs-set.md。
已有的 AGENTS.md 最特殊（它可能是别人手写的）：按有没有内核标记分三种——不存在就
直接生成、有标记就刷新、没有标记时脚本默认不动它，只输出一份体检，要升级结构加
--upgrade。判据与「手写文件为什么默认不动」见 references/docs-set.md。
因此遇到这类项目，P4 的正确顺序是：先跑一次脚本看体检报告（此时它不会改任何
东西）→ 把报告里「需要读代码后自己写」的那几节读代码写出来 → 需要升级结构时加
--upgrade → 最后再跑一次确认待填写归零。
执行流程
| 阶段 | 动作 | 参考 |
| P0 定位 | 确定目标目录。候选不唯一时问一次；问不到人时禁止默认选定，停下列候选清单进汇报待下会话续接。同时定范围（见「默认范围」）：没说范围就是全量，点名了就只做那几件；它是 P7 传不传 --scope 的依据 | — |
| P1 勘察 | 跑勘察脚本，读关键文件补齐意图 | references/survey.md |
| P2 判定 | 用能力矩阵逐行求值，算出做哪几件、跳过哪几件，向用户复述一句结论（被委派时用户指调用方，写进回执等指示），并预告后面要用户定的事（许可证意向、署名来源、可见性意向、账号/组织、要不要接受外部贡献、要不要 CI 自动发布——此时只预告不问，P4–P6 再落实） | 本文件 |
| P3 版本管理 | 文本属性 → 忽略规则 → 署名 → 密钥扫描 → 首次提交 | references/version-control.md |
| P4 文档 | 先过 G7 问清只有用户能定的事；再生成 AGENTS.md 并确认待填写项归零，然后写 README + CONTRIBUTING + LICENSE（用户选定后才写）；用户说要接受外部贡献时，落 .github/pull_request_template.md 与 .github/ISSUE_TEMPLATE/ 下的缺陷、需求两份模板（骨架在 templates/，不要手写）；要发版的项目还要落一份发版规范（RELEASING.md），它的章节结构只在 G7 问一次、不套通用模板；每写完一批非 AGENTS.md 的产物（含 .github/ 下那几份），跑一次 compose-agents.mjs <项目> --record <路径> [更多路径...] 记账——--record 一次可给多份（全有或全无），不记则交棒只能靠形状猜；目标仓库自带本地 skills 时按通用协议盘点保留（见 references/plugin-project.md 第十二节）；收尾跑 scripts/review.mjs，无[缺]、[待问]有 flag 用 flag、无 flag 改文件消掉才算完 | references/docs-set.md |
| P5 远端 | 发现通道 → 建仓库（默认私有）→ 推送 → 元数据 → 回读校验 → 回头再跑一次 P4 的脚本补远端相关节（强制） → 工作流从模板落盘，review.mjs 复验 → 把这两步的改动提交并再推送一次（它们是在首次推送之后才产生的，不补这一步，远端就永远缺它们，而本地看上去一切正常） | references/remote-github.md |
| P6 发布 | 仅当 P2 判定可发布。先回四问答案，再预演（清单贴进汇报），再发布，最后回读确认。发布说明在打标签之前就要写好并推上去（它是版本库里的一个文件，路径与结构以项目的发版规范为准）——顺序反了，远端自动化读不到文件，发版直接失败 | references/publish.md、references/remote-github.md |
| P7 验证汇报 | 跑该项目勘察到的门禁命令；校验远端与文档；按「做了什么 / 结果如何 / 下一步建议」汇报。P0 记下的局部诉求在这里传 review.mjs --scope=<切面>：只验那几面，其余不报缺 | — |
| P8 交棒（常规收尾，仅用户可达时） | P7 完成后主动提出：勘察痕迹 → 报告 → 等用户明确确认 → 按顺序拆 → 复验。无人值守时不执行，把待确认项写进汇报 | references/handoff.md |
P0–P8 是「把项目配起来」，配完之后是「每天怎么用它」——那条线不走阶段编号，按需读：
| 什么时候 | 读什么 |
| 有改动要落地（修缺陷、加能力、改文档、升级依赖） | references/collaboration.md：先判角色与改动性质，再决定主干直推还是分支 + 提案 |
| 一件事要跨会话、或可能换人接手 | 同上第二节：工作记录放哪、叫什么名、完成的怎么处置；骨架 templates/work-item.md |
| 用户把一段 Issue 正文、Issue 链接或一段报错贴进来 | 同上第一节「外部报告：从贴进来的那段话到一次能定位的修复」——先核实四要素、不盲猜写代码 |
| 用户把一个提案链接、或「有人提了个改动」贴进来 | 同上第一节「外部提案：别人已经改好了」——先只读 diff、判它有没有说清要解决什么；没开问题不是退回的理由 |
| 收外部报告或外部提案 | 同上第四、六节：审查读书单、外部贡献的信任边界 |
| 要派审查（子代理或新会话） | 同上第四节「怎么派」：只给材料清单，不给执行者的思路与上一轮结论；通过之后才合并 |
| 要合并、或要判断谁能合 | 同上第五节：风险分级、弱化门禁的一票否决 |
| 合并之后 | 同上第七节：六步顺序与四个坑（含平台自动删分支那种完成态） |
| 要在平台上发 Issue、提案或审查评论 | 同上第九节：正文一律走文件，不拼命令行 |
动手之前先跑一次自动更新（它可能把本文件换掉，所以要放在任何读取之前）：
node "<本领目录>/scripts/update.mjs" --quiet它让这份副本保持最新，你不需要为它做什么。--quiet 下没输出 = 没有可动作的变化；
它说「已更新」时你手上这份文件已经过期，重新读 SKILL.md 再继续。把它的输出原样转给
用户——包括那句「这份停在某一版、而且是核对不了」，那不是故障，是用户有权知道的事。
宿主禁止 skill 自改（沙箱只读、审计要求）或本次不想动安装目录时，设环境变量
PF_NO_UPDATE 为非空值即可整个关掉；要主动查一次版本用 --check，它不受任何节流。
两条路、窗口、同源校验这些机制细节在 README 的「更新」一节，本文件不复述。
几条只在特定情况下才用到的判据，按需读（写下来是为了不靠回忆）：
- P7 针对的是目标项目，不是本 skill；项目没有门禁命令时交付不能被说成「已验证」
——见
references/docs-set.md第十节； - 问不到人时怎么办（被委派的子代理、无人值守运行）：见
references/docs-set.md第一节「用户不可达时怎么办」——判据是问不到人不能成为停顿的理由，也不能成为自作主张 的借口：用默认值推进，把决定权留清楚； - 判定为插件类时，
references/plugin-project.md在 P1 之后就该读（它影响 P3 的 产物入库判断、P4 的发布范围写法、P5 的发布范围核对）；该文件同时给出判定协议：遇到 没有专章的插件生态时按它的判定协议去查，再把答案沉淀成新专章（references/plugins/）。
硬门控
这些是必须先读全文才能动手的关卡。判据全在指向的那份文件里，本节只回答「什么时候必须去读」。
| 门控 | 条件 | 必须先读 |
| G1 | 任何写入之前 | references/survey.md，且勘察已跑完 |
| G2 | 首次提交之前 | references/version-control.md；且已按密钥门控处置、无新增凭据进本次提交 |
| G3 | 写任何文档之前，以及 P7 汇报之前 | references/docs-set.md |
| G4 | 建仓库 / 推送之前 | references/remote-github.md；且已给用户确认清单（被委派时写进回执等指示，不直接执行） |
| G5 | 任何发布动作之前 | references/publish.md；涉及具体生态时加读对应 references/publish-<生态>.md；且说明文件已按项目的发版规范写好、提交并推送（references/remote-github.md 第六节） |
| G6 | P2 判定为插件类时，进 P3 之前 | references/plugin-project.md；有对应专章时一并读 references/plugins/<生态>.md |
| G7 | 写任何文档之前（只有用户能定的事一次问清） | 见下 |
| G8 | 判定为 skill 时，P1 之后即读 | references/skill-project.md；宿主有专章时一并读那张索引里指的专章 |
| G9 | 拆除本 skill 留下的痕迹之前（交棒或撤销） | references/handoff.md |
| G10 | 有远端、而这次改动要落地（收外部报告、审改动、合并、收尾） | references/collaboration.md |
| G11 | 盘点目标仓库自带的本地 skills 之前（与生态无关） | references/plugin-project.md 第十二节 |
G7：只有用户能定的事，一次问清。 那几件事脚本推不出来、也不能替用户决定，而且都只在
写文档时才需要，所以集中到一处问完，不要分几次打断。哪几件、为什么不能替你定、
要不到时怎么办，全在 references/docs-set.md 的「选择」一节——那份清单会随项目经验
增减，本文件不抄（抄了两处都要改，而漏改的那一处会静默失效）。
review.mjs 的[待问]要用 flag 消掉，flag 全集以 node scripts/review.mjs --help 为准。
发布说明的章节结构必须问：不同项目的读者关心的事不同（库看接口变化，工具看行为变化，
插件看宿主兼容性），套一份通用结构只会让每个项目都写得像别人家的。问的是「要回答读者
哪几个问题」，不是「照抄哪几节」——templates/release-spec.md 给的是默认菜单
（一节必需 + 几类按需），项目删减完把选定的那几节写进它自己的发版规范。
环境要求的最低版本不问：由勘察给出（artifacts.runtimeRequirements），
读得到就照抄，没声明就不写那一节——去问脚本本来就知道的数字，答错就写进了 README。
G4 的确认清单见 references/remote-github.md 建仓节表格。它与 P2 那句结论不是一回事：
P2 说本次任务做什么，G4 说这次对外动作具体是什么（确切仓库名、可见性、分支）。
不可逆或对外的动作都走 G4 式对齐，纯本地写入不需要；改可见性最危险，默认答案是「不做」。
怎么用
先读协议，再跑脚本——G1 要求任何写入前读完 references/survey.md，而勘察本身是
只读的，所以先跑勘察不会违规，但读协议要在动手之前完成。下面这几条命令里 <本 skill 目录>
指这个 skill 自己的位置（本文件所在目录），<项目目录> 指被处理的那个项目；两者通常
不同，命令可以在任意工作目录下执行，因为路径都是显式传入的。
# 1. 勘察目标项目（只读，不写任何东西）
node "<本 skill 目录>/scripts/survey.mjs" "<项目目录>" --markdown
# 2. 按 P2 的判定执行 P3 到 P7（详见上面的执行流程与各 reference）
# 3. 把通用内核注入目标项目的 AGENTS.md（幂等；标记区归内核独占，注入即刷新）
node "<本 skill 目录>/scripts/compose-agents.mjs" "<项目目录>"
# 4. P8 交棒：先勘察本 skill 在目标项目里留下的痕迹（只读），再按协议决定拆不拆
node "<本 skill 目录>/scripts/handoff.mjs" "<项目目录>" --scan维护本 skill 时跑 scripts/dev/preflight.mjs（按脚本自身位置推导检查对象，
不接受项目目录参数，不是 P7）。
各脚本零依赖、跨平台。含中文或空格的路径作为独立参数传入是正常用法
（不要拼进命令行字符串，理由见 references/remote-github.md 的 6.5）。
文件地图
包里有什么，不靠清单回答。 权威答案只有一个：git archive 那次真导出——
.gitattributes 的 export-ignore 决定哪几处不进包。自检按结构规则核对它，
不按任何一张要人记得改的登记表：清单会漏，而漏的症状是「文件在包里但没人知道」或
「该在却不在」，两种都不会自己出声。
所以本节只做一件事：告诉你该去读哪一份。需要时按下面的表查，不需要背。
判据（references/）：动手前按情境读全文
| 什么时候会用到它 | 读哪一份 |
| 每次任务开始 | references/survey.md——勘察协议、事实的含义、接着上次做 |
| 要动版本管理 | references/version-control.md——什么该入库、忽略规则、署名、密钥门控 |
| 要碰远端仓库 | references/remote-github.md——通道发现、建仓、推送、元数据、发版接线 |
| 改动要落地（收报告、审改动、合并、收尾） | references/collaboration.md |
| 要写任何文档 | references/docs-set.md——各文档的读者、职责、合并规则 |
| 要判断能不能发、发到哪 | references/publish.md，再按生态加读 publish-npm.md、publish-python.md、publish-go.md、publish-rust.md |
| 判定为插件类 | references/plugin-project.md；命中已知生态时加读 references/plugins/<生态>.md |
| 判定为能力目录类 | references/skill-project.md |
| 要交棒（拆掉自己留下的痕迹） | references/handoff.md |
落盘骨架（templates/）：照抄，不要改写
项目契约、说明、贡献指南、发版规范、工作记录、提案模板、两类问题模板、两份流水线， 以及几份许可证全文，都在这里。
它们是落盘产物，不是判据：写进项目的是一份能用的骨架；为什么这么写、哪里可以不一样，
一律在 references/ 里。同一段话两边各写一份，就一定会有一边先过期。
工具（scripts/）：AI 会跑到的那几条
node "<本领目录>/scripts/update.mjs" --quiet # 任何任务的第一步：先把副本换成最新
node "<本领目录>/scripts/survey.mjs" "<项目目录>" --markdown # P1 勘察（只读）
node "<本领目录>/scripts/compose-agents.mjs" "<项目目录>" # P4 生成/刷新契约（--check / --status / --upgrade / --record）
node "<本领目录>/scripts/review.mjs" "<项目目录>" # P4/P5 交付门禁（--scope 只验一面）
node "<本领目录>/scripts/handoff.mjs" "<项目目录>" --scan # P8 交棒（--verify 判干净）其余脚本（生态描述符、公共模块、发版说明发送、徽章核对、目录同步、解包）由上面这几个 按需调用，不需要另外记住。
这个仓库自己另有哪些文件（不进包的那些），写在 AGENTS.md 的「仓库里另有」一节——
那是维护这个 skill 时才需要读的东西，不是用这个 skill 的人需要的。
边界
做：版本管理的建立与维护、远端仓库的建立与元数据、文档套装的建立与同步、发布通道 的配置与发布本身、协作协议（收改动、审改动、谁能合、合并后怎么收尾）、 交棒时把自己在目标项目里留下的痕迹清干净。
不做：部署与服务器配置、容器编排、运行环境安装、代码本身的编写与重构、项目骨架的 生成（不选技术栈、不创建源码与框架配置文件）、代替项目执行日常开发（不写业务代码、 不代跑审查、不接管合并——它给的是协议，执行由项目里的 AI 按协议做）。
永不自动做：公开一个私有仓库、强制推送、改写已推送历史、删除已发布版本、替用户 决定许可证、替用户编造署名或账号、未经用户明确确认就拆掉自己留下的东西。
汇报纪律
- 每个阶段结束时同步进度，不要闷头做完再说。
- P2 的判定要复述给用户（做了哪些、跳过哪些、为什么），因为判定可能与用户预期不同。
- 收尾按「做了什么 / 结果如何 / 下一步建议」汇报。
- 收尾汇报里必须带一条交棒询问（措辞与硬不变量 10 那一处一致，问法见
references/handoff.md）。问不到人时把它写进汇报的待办，不要自作主张拆掉。 - 用户可见的改动完成后，只报版本号；文档与流程细节不必复述。
- 跳过某件事时要说清为什么跳过——「不发布」和「忘了发布」在用户看来是一样的。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.