doyourmagic

技能：doyourmagic

是什么

目的与背景

• 目的： 将刚克隆的外部仓库/工具转化为可运行的工作流技能包（hub /dym-<repo> + N 个子技能），附带 workflows.md（验证清单）和 flow.html；所有命令均已通过代码、--help 或实际运行进行核对，然后给出适配模式的判断。
• 触发条件（何时使用）：
  • 用户刚克隆/安装了外部仓库/CLI/工具，并想知道“这东西到底怎么用”，希望得到可以直接输入的内容，而不是每次都要重新阅读的 README。
  • 用户说“拉个新仓库回来”“doyourmagic ”“给这个工具做工作流”“为这个仓库生成工作流文档”“帮我写一份这个仓库可运行的使用说明”。
  • 在将外部工具纳入项目规范/CI 之前，先生成技能包，让集成决策基于已验证的命令，而非 README 的转述。
• 非目标： 不转述 README；不修改克隆内容（只读）；适配判断未经用户批准前，不在主仓库中自行搭建脚手架/集成；不推广 hub。

心智模型

克隆（沙盒，只读）→ 清单 → README = 假设 → 对照解析器/--help/实际退出状态 → 实际运行（固定范围）→ 按对象划分工作流 → 子技能 + hub → workflows.md + flow.html → 适配模式判断 →（可选）dym-sync 推送 / 安装 / 推广

输入与输出约定

	字段	必填？	含义
输入	外部工具仓库/URL	是	需要制作工作流的对象
输入	--name <prefix> / --humanize	否	命名模式（默认 dym-<repo>）
输入	机器上实际的集成版本	否	如果存在，优先于克隆中的 fixture
输出	.overstack/doyourmagic/<repo>/skills/<hub>/SKILL.md + <hub>-<slug>/SKILL.md	是	hub 含有 domains:；所有技能均设为 disable-model-invocation: true
输出	workflows.md + flow.html	是	验证清单（声明 → file:行 / 运行案例 / rc）；交付前实际打开 flow
输出	适配模式判断	是	融合 · 拉到外部 · 嵌入并自有 · 不采用

规则与能力

• RULE-01（必须）：不得将 README 转述为“可运行”内容——每条命令都必须出现在 manifest scripts / 实际 --help / 参数解析器中。
• RULE-02（必须）：不得假设退出码为 0/1——读取实际退出码；工具可能使用 2 表示“有发现”，也可能在缺少文件时 fail-open 返回 0，调用方必须正确分支处理。
• RULE-03（必须）：不得将工具的 .github/workflows/*.yml 搬进供使用者使用的技能 CI——应单独编写精简示例。
• RULE-04（必须）：聊天命令和 shell 命令不得放在同一个技能中。
• RULE-05（必须）：未固定范围时不得运行工具安装器（2026-09-04 测得：npx impeccable install --help 实际会安装到 $HOME 下的 13 个目录）。使用沙盒 + 隔离的 HOME + 明确指定范围的标志。
• RULE-06（必须）：对克隆内容只读；仅可写入 .overstack/doyourmagic/<repo>/。
• RULE-07（必须）：每个子技能都必须自包含；hub 只读取被调用的文件，不将整个技能包塞入上下文。
• RULE-08（必须）：flow.html 必须自包含（不使用 CDN，不使用本地绝对路径），支持明暗模式阅读，并可通过 file:// 打开。
• RULE-09（必须）：优先采用实际运行证据，而非引用；无法运行的内容须在原处标注“尚未验证”。
• 能力：在隔离的沙盒中克隆并读取外部仓库；在固定范围内运行工具命令；仅写入 .overstack/doyourmagic/<repo>/；通过浏览器打开 HTML 页面进行验证；（可选）通过同步工具 + PR 将技能包推送到共享仓库。

失败边界

• 无法通过代码/--help/实际运行核对的命令 → 不得写成“可运行”；须在原处标注**“尚未验证”**（部分完成）。
• 无法固定范围的安装器 → 该运行案例标记为阻止，不得运行。
• --humanize 与现有技能名称冲突 → 回退到默认模式并明确说明。
• 仓库 rheinmir/dym 中已有该仓库的技能包 → 拉取现有技能包，不要重新运行（如用户想重新运行，先与用户确认）。
• 判断为融合/嵌入 → 先停下询问，再搭建脚手架。

如何

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	效果	仓库	克隆到沙盒（第 1 步）；查看 rheinmir/dym 是否已有 bundle	只读克隆	已有 bundle → B03
W02	确定性	克隆	先看 Manifest，README 仅作假设，再对照 parser/--help/实际退出结果（第 2–3 步）	已对照的命令列表	无法对照 → “尚未验证”
W03	效果	命令	在沙盒中实际运行，固定 scope；如有则读取实际集成版本（第 4–5 步）	各案例的 rc	无法固定 scope → 跳过该案例
W04	判断	结果	按对象划分工作流，敲定名称（第 6–7 步）	hub/slug 列表	名称 --humanize 重复 → 默认
W05	效果	工作流	编写 sub-skill + hub + workflows.md（第 8–10 步）	磁盘上的 bundle	dym-sync.py lint 报错 → 修复
W06	效果	bundle	根据 docs-site-macos 生成 flow.html，并用浏览器实际打开（第 11 步）	已验证的 flow.html	显示错误 → 修复后重新打开
W07	判断	bundle	adapt-modes 门禁：给出一个 verdict（第 12 步）	verdict	HÒA TAN/NHÚNG → scaffold 前先询问

各步骤详情（W01–W07 的事实来源）：

1. 克隆到 sandbox（scratch 目录）——不要在用户的项目树中就地探索。对克隆的探索必须是只读的。
2. 先看清单，再看说明文字：在阅读 README 之前，先查找 package.json / pyproject.toml / Cargo.toml / go.mod / 安装脚本——它们能提供真正的安装命令、入口点/bin 和脚本列表。
3. **README/AGENTS.md/docs 都是假设，不是真相。**每条准备写出的命令，都必须对照参数解析器、实际运行的 --help、字面量 process.exit(...) sys.exit(...) 核实——读取实际退出码，不要假设是 0/1。
4. 在 sandbox 中用严格限定的范围运行所有可运行的内容（隔离 HOME、--scope=project、--no-verify……）：安装脚本、对脏/干净输入运行验证器、罕见模式、缺失文件。记录每种情况的 rc——workflows.md 中的验证表格以此为依据。
5. 如果机器上已有真正的集成实例（其他项目中已提交的配置）→ 读取它；对于“现实中正确用法是什么”，它比克隆中的 fixture 更可信。在真实实例上复现问题是最有力的证据。
6. 按对象而非功能划分工作流：使用（在自己的项目中使用工具）与贡献（修改工具本身）。聊天命令（/x）和 shell 命令应拆分为独立 skill——混在一起会导致复制粘贴出错。
7. 按 Naming 表确定名称（如果使用 --humanize，检查是否重复）。
8. 将每个工作流写成一个子 skill：.overstack/doyourmagic/<repo>/skills/<hub>-<slug>/SKILL.md：
   • frontmatter 使用 name: <hub>-<slug>，description = 一句话说明何时调用 + 触发关键词，并设置 disable-model-invocation: true——这样通过 npx skills add 安装整个 bundle（7 个 skill）时，不会有任何 description 内容自动塞进 context；只有输入命令时才会加载。
   • ## When to use——说明适用情境，以及“为什么运行／会生成什么”。
   • ## Steps——提供可直接复制粘贴的命令、准确路径、预期输出／退出码。实际运行过的命令要记录测得的 rc。
   • ## Rules——列出已测量而非猜测的陷阱及规避方法；说明“禁止执行”的例外情况。
   • 独立完整：不要引用克隆中才有的文件；必要时写“如果文件 X 存在，则……”。
9. 编写 hub：.overstack/doyourmagic/<repo>/skills/<hub>/SKILL.md：

   ---
   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>"
   ---
   ## Steps
   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.
   

10. workflows.md：包含一张表格（skill · 用途 · 分支 · 调用命令）、“建议执行顺序”、“代价最高的陷阱”、“如何验证”表格（断言 → 文件:行／实际运行案例／rc）、所用的命名模式，以及一行 symlink 命令（见下方 Install 部分）。
11. flow.html——根据 skill docs-site-macos 生成（必须具备：玻璃质感侧边栏、背景光球、可折叠思维导图、侧边栏底部的明暗切换按钮 + 防 FOUC、适合 13″ 屏幕的紧凑字号、skip-link/focus ring、页脚显示文件本身的绝对路径）。内容 = skill 的精确执行流程：每个 skill 一个节点，边的关系为 skill → 产物 → 下一个 skill（连接线由 JS 根据 getBoundingClientRect 绘制，调整窗口大小时重绘——不要硬编码坐标），按分支展示执行顺序，每个节点注明调用命令 + 产物 + 一行陷阱。术语需在括号中解释。交付前必须用真实浏览器（或 /playwright-verify）打开检查——只读代码不够。
12. adapt-modes 门禁——bundle 不是最终目标。给用户一个且仅一个 verdict：融入（改写为我们自己的代码／skill）· 外置拉取（pointer + pin）· 内嵌自有（vendor）· 不采用（说明已有何种覆盖及其路径）。按决策成本维度比较——每次使用需要多少个 Agent 调用、生成的代码是否可不经 LLM 使用——不要比较字节数。若 verdict 为“融入”／“内嵌”，需先询问，再进行脚手架搭建。

分支

ID	类型	条件	行为	跳过 / 失败	汇合点
B01	用户可选	--name <prefix> 或 --humanize	按 Naming 表命名；--humanize 必须先检查是否重名	重名 → 回退到默认命名，并明确说明	W05
B02	能力可选	机器上已有真实集成版本（在其他项目中提交的配置）	读取该版本，优先于克隆中的 fixture；在真实版本上重现问题	不存在 → 跳过	W04
B03	有条件必需	rheinmir/dym 中已有该 repo 的 bundle	拉取（npx skills add rheinmir/dym 或克隆），而不是重新运行	用户想重新运行 → W02	结束
B04	用户可选	bundle 完成后，用户想分享/使用	使用 dym-sync.py 执行 lint/index/install/check/push；或在本地创建 hub 的 symlink；或将 sub-skill 提升到主 repo	缺少 gh → push 停止	结束

验证与停止

workflows.md 中的“如何验证”表格：每项声明都指向 file:line / 真实运行案例 / rc——缺少时标注“尚未验证”。python3 harness/scripts/dym-sync.py lint 通过（bundle 格式为 SKILL，hub 包含 domains:）。必须实际打开 flow.html。在 adapt-modes 判定处停止；只有用户批准后才 scaffold。

示例

• 正向： /doyourmagic https://github.com/Rheinmir/setup → 克隆 sandbox，阅读 installer 和真实的 --help，在脏/干净输入上运行 validator 并记录 rc → hub dym-setup + 6 个 sub-skill，workflows.md 中包含 30 行验证表格，实际打开 flow.html → 判定（参见 references/example-setup/）。
• 边界/失败： 工具有 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；只有用户输入 /<hub> <slug> 时，才会读取子工作流正文。这是 /fdk 的“单名称 hub，描述适用范围”模式，而不是在 context 中散布 N 个 skill。
• Sub-skill 是真正的 SKILL.md（不是文档）：将整个目录原样复制到主 repo 的 skills/，即可成为通过 npx skills add 安装的 skill。
• 不再有 NN-*.md：可运行内容位于 sub-skill 的 Steps 中——只有一个来源，不会有并行文档版本发生漂移。

参考 — 命名 — 3 种模式，将使用的模式记入 workflows.md

模式	Hub	Sub-skill	适用情况
默认	dym-<repo>	dym-<repo>-<slug>	用户未指定。绝不重名，名称能看出来源；提升时再重命名
--name <prefix>	<prefix>	<prefix>-<slug>	用户自定义
--humanize	Agent 取一个简短、容易输入的名称（例如 overstack）	<hub>-<slug>	必须先运行 ls ~/.claude/skills .claude/skills 检查是否重名，再确定名称；重名 → 回退到默认命名，并明确说明
<repo> = repo 名称（URL 的最后一段，去掉 .git），使用小写字母，特殊字符替换为 -。<slug> = 用 1–2 个词描述用途（install、ci、contributor），不加编号。

参考 — 同步 + 路由 — harness/scripts/dym-sync.py（stdlib，0 token）

S=harness/scripts/dym-sync.py
python3 $S lint                       # mọi bundle phải ở DẠNG SKILL (hub có `domains:`); dạng cũ NN-*.md → `migrate <repo> --domains chart,report`
python3 $S index                      # sinh meta-hub .overstack/doyourmagic/dym/SKILL.md: bảng domain → hub → slug
python3 $S install [dym|<repo>] [--auto slug,slug]   # symlink vào .claude/skills; --auto = bỏ disable-model-invocation, agent tự nạp theo description
python3 $S check [--yes]              # đĩa ↔ baseline ↔ dym: NEW-LOCAL/SAME/LOCAL/REMOTE-AHEAD/CONFLICT; hỏi y/N rồi push. Hook Stop tự nhắc khi phiên đụng bundle.
python3 $S push <repo> [--yes]        # copy vào clone dym → nhánh dym/<repo> → PR (gh); ghi .dym-baseline.json

Hub 必须在 frontmatter 中声明 domains: [a, b]——/dym（占用 1 行 context，可由 model 调用）读取 domain 表以自动选择 bundle：chart → lieflat-charts，frontend → impeccable……Hub 和 sub-skill 仍设置为 disable-model-invocation，仅在被调用时加载。

参考 — 已运行的 bundle 仓库 — rheinmir/dym

每次运行完成后，dym-sync.py push <repo> 会将 .overstack/doyourmagic/<repo>/ 推送到 https://github.com/Rheinmir/dym，作为 <repo>/ 提交（PR），让其他人拉取，而不是重新运行：npx skills add rheinmir/dym（安装 hub + sub-skill，限定项目范围；添加 -g 可全局安装），或 git clone --depth 1 https://github.com/Rheinmir/dym.git doyourmagic-bundles。运行新的 /doyourmagic <repo> 之前：检查那里是否已有 bundle。

参考 — 安装（本地使用）— 一条命令，仅在需要时加载

mkdir -p .claude/skills && ln -sfn ../../.overstack/doyourmagic/<repo>/skills/<hub> .claude/skills/<hub>

仅将 hub 加载到上下文中。输入 /<hub> 查看 slug 表，输入 /<hub> <slug> 运行一个工作流。若想直接调用 /<hub>-<slug>，则仅为对应目录添加符号链接——每增加一个符号链接，就会增加一行上下文，请酌情考虑。

参考 — 提升到主仓库（通过 npx 安装的 skill）

/fdk 路径已就绪，无需额外创建工具：

bash <(curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/fdk/tools/fdk-kit.sh) pull   # lần đầu
cp -R .overstack/doyourmagic/<repo>/skills/<hub>-<slug> .overstack/kit/skills/<tên-mới>          # đổi tên nếu bỏ tiền tố dym-
cd .overstack/kit && python3 fdk/tools/new-skill.py <tên-mới> --dry-run                # in checklist register
# register: LOOP_MAP (sync-skills.py) · LOOP_GROUPS · marketplace.json · bảng AGENT.md+CLAUDE.md · provenance
bash fdk/tools/fdk-kit.sh check && bash fdk/tools/fdk-kit.sh submit skill/<tên-mới> "<mô tả>"

修改 frontmatter 中的 name: 以匹配新名称；保留用于触发的 description。不要提升 hub（它只有与 bundle 放在一起才有意义）。

参考示例

references/example-setup/ — 此 skill 在 rheinmir/setup 上的一次真实运行（overstack：bootstrap + 19 条规则 + 87 个 skill）：hub dym-setup + 6 个子 skill（子文件保存为 <名称>.skill.md，避免被 loader 误扫为 skill）、包含 30 行验证表的 workflows.md、flow.html。此次运行发现了 5 个真实问题（已在 PR #114–#117 中修复）——这就是需要达到的“验证”水平。