• Purpose： 将一个刚 clone 的外部 repo/tool 转换为一套可实际运行的 workflow skill bundle（hub

  /dym-<repo>

  + N 个 sub-skill），并附带

  workflows.md

  （验证表）和

  flow.html

  ；所有命令都要与代码/

  --help

  /实际运行结果交叉验证，然后给出一个 adapt-modes verdict。
• Trigger（何时使用）：
  • 用户刚 clone/install 一个外部 repo/CLI/tool，希望把“这个东西到底怎么用”变成可以直接输入执行的内容，而不是每次都要重新阅读 README。
  • 用户说出「kéo repo mới về」、「doyourmagic <repo>」、「làm workflow cho tool này」、「generate workflow docs for this repo」或「viết hộ cách dùng runnable cho repo này」。
  • 在将外部 tool 纳入项目规范或 CI 之前，先产出 bundle，使集成决策建立在经过验证的命令之上，而不是对 README 的转述。
• Non-goals： 不转述 README；不修改 clone（只读）；在 verdict 尚未获得用户批准前，不自动 scaffold 或集成到主 repo；不 promote hub。

• RULE-01（MUST）：不得将 README 转述成“可运行”内容——每条命令都必须存在于 manifest scripts、真实的

  --help

  输出或 argument parser 中。
• RULE-02（MUST）：不得假定退出码为 0/1——必须读取真实的 exit code；tool 可能用 2 表示“有 finding”，也可能在缺少文件时 fail-open 并返回 0，调用方必须正确分支。
• RULE-03（MUST）：不得将 tool 自身的

  .github/workflows/*.yml

  复制进供消费者使用的 skill CI；应单独编写最小示例。
• RULE-04（MUST）：chat 命令和 shell 命令不得放在同一个 skill 中。
• RULE-05（MUST）：未锁定 scope 时不得运行 tool 的 installer（2026-09-04 实测：

  npx impeccable install --help

  实际向

  $HOME

  中的 13 个目录安装了内容）。必须使用 sandbox、隔离的

  HOME

  以及明确的 scope 参数。
• RULE-06（MUST）：对 clone 保持只读；只能写入

  .overstack/doyourmagic/<repo>/

  。
• RULE-07（MUST）：每个 sub-skill 必须自包含；hub 只读取被调用的那个文件——不得将整个 bundle 塞入 context。
• RULE-08（MUST）：

  flow.html

  必须自包含（不使用 CDN，不使用本地绝对路径），同时支持浅色和深色模式，并能通过

  file://

  打开。
• RULE-09（MUST）：优先采用实际运行证据，而不是引用；无法运行的内容必须就地标记为“未验证”。
• Capabilities：在隔离的 sandbox 中 clone 并读取外部 repo；以锁定的 scope 运行 tool 命令；仅写入

  .overstack/doyourmagic/<repo>/

  ；使用浏览器打开 HTML 页面进行 verify；（可选）通过同步工具和 PR 将 bundle 推送到共享仓库。

• 命令无法与代码/

  --help

  /实际运行结果交叉验证 → 不得将其写为“runnable”；应就地标记为**“未验证”**（partial）。
• Installer 无法锁定 scope → 该用例为 blocked，不得运行。

• --humanize

  生成的 skill 名与现有名称冲突 → 回退到默认模式，并明确说明。

• rheinmir/dym

  中已经存在该 repo 的 bundle → 优先拉取现有 bundle，而不是重新运行（如果用户希望重新运行，则先 clarify）。
• Verdict 为 HÒA TAN/NHÚNG → 在 scaffold 前必须先询问用户。

rheinmir/dym

--help

--humanize

workflows.md

dym-sync.py lint

docs-site-macos

flow.html

1. Clone 到 sandbox（scratch dir）——不要直接在用户项目树中探索。对 clone 的探索必须保持只读。
2. Manifest 优先，prose 在后：在读取 README 之前，先查找

   package.json

   /

   pyproject.toml

   /

   Cargo.toml

   /

   go.mod

   / installer script；它们能够提供真实的安装命令、entry point/bin 和脚本列表。
3. README/AGENTS.md/docs 只是假设，不是事实。准备写入的每条命令都必须与 argument parser、实际运行的

   --help

   或字面量

   process.exit(...)

   /

   sys.exit(...)

   交叉验证；必须读取真实退出码，不得假定为 0/1。
4. 尽可能实际运行能够在 sandbox 中运行的命令，并严格锁定 scope（隔离的

   HOME

   、

   --scope=project

   、

   --no-verify

   等）：测试 installer、在脏输入/干净输入上运行 validator、特殊模式以及文件缺失场景。记录每个用例的 rc——

   workflows.md

   的验证表由此生成。
5. 如果机器上已经存在真实集成版本（例如另一个项目提交的配置）→ 读取它；在“真实世界中的正确用法”方面，它优先于 clone 中的 fixture。在真实版本上复现错误是最有力的证据。
6. 按对象而非按功能拆分 workflow：消费（在自己的项目中使用 tool）与贡献（修改 tool 本身）。chat 命令（

   /x

   ）和 shell 命令必须拆成独立的 skill——混在一起会产生容易失效的 copy-paste 内容。
7. 按 Naming 表确定名称（使用

   --humanize

   时检查名称冲突）。
8. 将每个 workflow 写成一个 sub-skill：

   .overstack/doyourmagic/<repo>/skills/<hub>-<slug>/SKILL.md

   ：
   • frontmatter 包含

     name: <hub>-<slug>

     ；

     description

     用一句话说明何时调用并包含 trigger 关键词；还必须包含

     disable-model-invocation: true

     ——这样即使通过

     npx skills add

     安装整个 bundle（7 个 skill），也不会自动将任何 description 塞入 context；只有用户输入时才会加载。

   • ## When to use

     ——描述适用场景，以及“为什么运行／会生成什么”。

   • ## Steps

     ——提供可直接 copy-paste 的命令、精确路径以及预期的 output/退出码。已经实际运行过的命令必须记录测得的 rc。

   • ## Rules

     ——记录已经实测出的陷阱（不是猜测），并说明规避方式；明确列出“不得执行”的 carve-out。
   • Self-contained：不得引用仅存在于 clone 中的文件；如果需要，则写成“如果文件 X 存在，则……”。
9. 编写 hub：

   .overstack/doyourmagic/<repo>/skills/<hub>/SKILL.md

   ：

   undefined

name: <hub> disable-model-invocation: true domains: [<domain-1>, <domain-2>] # bắt buộc — /dym định tuyến theo đây (chart · frontend · diagram · security · …) source: <url repo gốc> description: "<một dòng: tool gì · gõ /<hub> <slug> · slugs: a · b · c>"

1. Đọc ARGUMENTS → <slug>. Không có slug → in bảng slug + một dòng mục đích, dừng.
2. Tìm file con theo thứ tự, lấy file ĐẦU TIÊN tồn tại rồi đọc ĐÚNG MỘT file: (1)

   .claude/skills/<hub>-<slug>/SKILL.md

   — đã cài qua

   npx skills add rheinmir/dym

   ; (2)

   .overstack/doyourmagic/<repo>/skills/<hub>-<slug>/SKILL.md

   — bundle nằm trong dự án, hub symlink; (3)

   doyourmagic-bundles/<repo>/skills/<hub>-<slug>/SKILL.md

   — clone

   rheinmir/dym

   cạnh dự án. Làm theo Steps/Rules của file đó; không đọc file con khác; không thấy cả 3 → nói rõ, dừng.

   undefined

3. workflows.md

   ：包含表格（skill · 用途 · 分支 · 调用命令）、“建议执行顺序”、“代价最高的陷阱”、“如何验证”表（断言 → file:行号／实际运行用例／rc）、已采用的命名模式，以及一行 symlink 命令（见下方 Install）。

4. flow.html

   ——按

   docs-site-macos

   skill 生成（必须具备：全屏 sidebar、background orbs、可折叠 mind map、位于 footer sidebar 的明暗切换按钮并防止 FOUC、适合 13″ 屏幕的紧凑字号、skip-link/focus ring，以及在 footer 中显示该文件自身的绝对路径）。内容必须呈现各 skill 实际执行的准确流程：每个 skill 一个节点，连接线表示

   skill → 产物 → 下一 skill

   （connector 由 JS 根据

   getBoundingClientRect

   绘制，并在 resize 时重绘——不得硬编码坐标）；按分支展示执行顺序；每个节点写明调用命令、产物和一行陷阱说明。术语应在括号中给出解释。交付前必须使用浏览器实际打开（或使用

   /playwright-verify

   ）——只阅读代码并不足够。
5. Adapt-modes gate——bundle 不是终点。向用户提供一个 verdict：HÒA TAN（改写为我们自己的代码/skill）· KÉO NGOÀI（pointer + pin）· NHÚNG-SỞ-HỮU（vendor）· KHÔNG LẤY（已有方案覆盖，记录 path）。比较时应基于成本决策轴——每次使用的 agent 轮数、无需 LLM 即可生成的代码——而不是比较字节数。Verdict 为 HÒA TAN/NHÚNG 时，必须在 scaffold 前先询问。

• Positive：

  /doyourmagic https://github.com/Rheinmir/setup

  → clone 到 sandbox，读取 installer 和真实的

  --help

  ，在脏输入/干净输入上运行 validator 并记录 rc → hub

  dym-setup

  + 6 个 sub-skill，生成包含 30 行验证内容的

  workflows.md

  ，实际打开

  flow.html

  → verdict（参见

  references/example-setup/

  ）。
• Boundary/failure： tool 包含

  npx <tool> install

  ，但

  --help

  未列出 scope 参数 → 不运行 installer（它会实际安装到

  $HOME

  ）；sub-skill 仍须为安装命令记录“未验证”以及已知陷阱。

.overstack/doyourmagic/<repo>/
  workflows.md                  # chỉ mục + thứ tự chạy + bảng "kiểm chứng thế nào" (thứ không thuộc về một skill nào)
  flow.html                     # docs-site-macos: sidebar · mind map · SƠ ĐỒ LUỒNG skill→sản phẩm→skill kế · toggle sáng/tối
  skills/
    <hub>/SKILL.md              # /<hub> <slug> — 1 dòng description, disable-model-invocation, đọc ĐÚNG file con được gọi
    <hub>-<slug-1>/SKILL.md     # mỗi workflow = một skill đầy đủ (frontmatter + When/Steps/Rules), tự chứa, promote được
    <hub>-<slug-2>/SKILL.md

• Hub 是唯一会被 symlink 到

  .claude/skills/

  的内容 → context 只消耗一行 description；子 workflow 的正文仅在用户输入

  /<hub> <slug>

  时读取。这就是

  /fdk

  使用的“单名称 hub、描述范围”模式，而不是将 N 个 skill 散落在 context 中。
• Sub-skill 是真正的 SKILL.md（不是普通文档）：将整个目录复制到主 repo 的

  skills/

  后，即可成为通过

  npx skills add

  安装的 skill。
• 不再保留

  NN-*.md

  ：可运行内容全部位于 sub-skill 的 Steps 中——只保留一个事实来源，避免并行文档产生 drift。