doyourmagic

スキル：doyourmagic

概要

目的とコンテキスト

• 目的： clone したばかりの外部 repo/tool を、実行可能なワークフロースキルバンドル（ハブ /dym-<repo> ＋ N 個のサブスキル）に変換し、workflows.md（検証表）と flow.html を作成します。すべてのコマンドはコード／--help／実際の実行結果と照合済みで、最後に adapt-modes の verdict を提示します。
• トリガー（使用する場面）：
  • ユーザーが外部 repo/CLI/tool を clone／インストールしたばかりで、「これを実際にどう使えばいいのか」を、毎回 README を読み直すのではなく、入力して実行できる形で知りたい場合。
  • ユーザーが「新しい repo を持ってきた」「doyourmagic 」「この tool のワークフローを作って」「この repo のワークフロードキュメントを生成して」「この repo の実行可能な使い方を書いて」と言った場合。
  • 外部 tool をプロジェクトの規約／CI に組み込む前に、まずバンドルを作成します。README の言い換えではなく、検証済みのコマンドに基づいて統合を判断できます。
• 対象外： README の言い換えはしません。clone を変更しません（読み取り専用）。verdict がユーザーに承認される前に、メイン repo への scaffold／統合を自動で行いません。ハブを昇格させません。

メンタルモデル

clone（サンドボックス、読み取り専用）→ manifest → README ＝ 仮説 → parser／--help／実際の終了コードと照合 → 実行（scope を固定）→ 対象別にワークフローを分割 → サブスキル＋ハブ → workflows.md＋flow.html → adapt-modes verdict →（任意）dym-sync push／install／昇格

入力と出力の契約

	フィールド	必須？	意味
入力	外部 tool の repo/URL	はい	ワークフロー作成の対象
入力	--name <prefix> / --humanize	いいえ	名前の付け方（デフォルトは dym-<repo>）
入力	マシン上の実際の統合版	いいえ	存在する場合は clone 内の fixture より優先
出力	.overstack/doyourmagic/<repo>/skills/<hub>/SKILL.md ＋ <hub>-<slug>/SKILL.md	はい	domains: を持つハブ。すべてのスキルに disable-model-invocation: true を設定
出力	workflows.md ＋ flow.html	はい	検証表（主張 → file:行／実行ケース／rc）。引き渡す前に flow を実際に開く
出力	adapt-modes verdict	はい	融合・外部として取り込む・所有物として埋め込む・採用しない

ルールと機能

• RULE-01（必須）：README を「実行可能」な内容に言い換えてはいけません。各コマンドは manifest scripts／実際の --help／argument parser のいずれかで確認できる必要があります。
• RULE-02（必須）：終了コードを 0／1 と決めつけてはいけません。実際の終了コードを読み取ります。tool は「finding あり」を 2 で示したり、ファイルがない場合に fail-open で 0 を返したりすることがあるため、呼び出し側は正しく分岐する必要があります。
• RULE-03（必須）：tool の .github/workflows/*.yml を利用者向けの skill CI にそのまま持ち込んではいけません。独自の簡潔な例を作成します。
• RULE-04（必須）：チャットのコマンドとシェルのコマンドを同じスキルに入れてはいけません。
• RULE-05（必須）：scope を固定せずに tool の installer を実行してはいけません（2026-09-04 に計測：npx impeccable install --help は $HOME に実際に 13 個のディレクトリをインストールしました）。サンドボックス＋隔離した HOME＋明示的な scope フラグを使います。
• RULE-06（必須）：clone は読み取り専用にします。書き込み先は .overstack/doyourmagic/<repo>/ のみにします。
• RULE-07（必須）：各サブスキルは自己完結させます。ハブは呼び出されたファイルだけを読み込み、バンドル全体をコンテキストに詰め込みません。
• RULE-08（必須）：flow.html は自己完結させます（CDN、ローカルの絶対パスは使いません）。明るいテーマと暗いテーマの両方で読みやすくし、file:// 経由で開けるようにします。
• RULE-09（必須）：引用より実際の実行証拠を優先します。実行できていないものは、その場に「未検証」と記載します。
• 機能：隔離されたサンドボックス内で外部 repo を clone して読み取り可能。scope を固定して tool のコマンドを実行可能。.overstack/doyourmagic/<repo>/ 以下にのみ書き込み可能。ブラウザーで HTML ページを開いて検証可能。（任意）同期ツール＋PR を通じてバンドルを共有リポジトリにプッシュ可能。

失敗時の境界

• コマンドをコード／--help／実行結果と照合できない場合、「実行可能」として記述してはいけません。その場に**「未検証」**と記載します（部分対応）。
• Installer の scope を固定できない場合、その実行ケースはブロックし、実行しません。
• --humanize が既存のスキル名と重複する場合はデフォルトモードに戻し、そのことを明記します。
• rheinmir/dym リポジトリに対象 repo のバンドルがすでにある場合は、再実行せずに取得します。再実行を希望する場合は、ユーザーに確認します（確認）。
• verdict が融合／埋め込みの場合は、scaffold に進む前に停止して確認します。

手順

メインワークフロー

ステップ	種別	入力	アクション	出力／終了	失敗時／次の処理
W01	effect	repo	サンドボックスにクローンします（ステップ1）。rheinmir/dym にすでにバンドルがあるか確認します	読み取り専用のクローン	バンドルがある場合 → B03
W02	deterministic	clone	まずマニフェストを確認し、README は仮説として扱い、パーサー／--help／実際の終了コードと照合します（ステップ2～3）	照合済みコマンド一覧	照合できない場合 → 「未検証」
W03	effect	コマンド	サンドボックス内で実行し、スコープを固定します。実際の統合済みバージョンがあれば読み込みます（ステップ4～5）	各ケースの rc	スコープを固定できない場合 → そのケースを除外
W04	judgment	結果	対象ごとにワークフローを分け、名前を決定します（ステップ6～7）	ハブ／slug の一覧	--humanize の名前が重複する場合 → デフォルト
W05	effect	ワークフロー	サブスキル、ハブ、workflows.md を作成します（ステップ8～10）	ディスク上のバンドル	dym-sync.py lint がエラーの場合 → 修正
W06	effect	バンドル	docs-site-macos に従って flow.html を生成し、実際にブラウザーで開きます（ステップ11）	検証済みの flow.html	表示エラー → 修正して再度開く
W07	judgment	バンドル	adapt-modes ゲート：判定は1つのみ（ステップ12）	判定	HÒA TAN／NHÚNG → スキャフォールドの前に確認

各ステップの詳細（W01～W07 の信頼できる情報源）：

1. sandbox にクローンする（scratch dir）— ユーザーのプロジェクトツリー内で直接調査しないでください。クローンの調査は読み取り専用です。
2. 説明文より先にマニフェストを確認する：README を読む前に、package.json / pyproject.toml / Cargo.toml / go.mod / installer script を探してください。実際のインストールコマンド、エントリーポイント／bin、スクリプト一覧がわかります。
3. README/AGENTS.md/docs は仮説であり、事実ではありません。記述する各コマンドは、argument parser / 実際に実行した --help / リテラルの process.exit(...) sys.exit(...) と照合してください。実際の終了コードを読み、0/1 と決めつけないでください。
4. sandbox で実行できるものは、スコープを厳密に固定して実際に実行してください（隔離した HOME、--scope=project、--no-verify…）：installer、汚れた／クリーンな入力に対する validator、未知の mode、ファイル欠損。各ケースの rc を記録してください。workflows.md の検証表はここから作成します。
5. 実際に統合されたものがすでにある場合（別プロジェクトにコミット済みの設定）→それを読みます。「実運用では正しくどう見えるか」については、クローン内の fixture よりも優先されます。実物で問題を再現できれば、最も強力な証拠になります。
6. ワークフローは機能別ではなく対象者別に分ける：利用（自分のプロジェクトでツールを使う）と貢献（ツール自体を変更する）。チャットコマンド（/x）とシェルコマンドは別の skill に分けます。混在させるとコピー＆ペーストで壊れます。
7. Naming 表に従って名前を確定します（--humanize の場合は重複を確認）。
8. 各ワークフローを sub-skill として作成します .overstack/doyourmagic/<repo>/skills/<hub>-<slug>/SKILL.md：
   • frontmatter は name: <hub>-<slug、description は「いつ呼び出すか」＋トリガーキーワードを示す1文とし、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 · 目的 · 分岐 · 呼び出しコマンド）、「推奨実行順序」、「最もコストの高い落とし穴」、「検証方法」表（主張 → file:line / 実行したケース / rc）、使用した命名方式、1行の symlink コマンド（以下の Install 項目）。
11. flow.html — skill docs-site-macos に従って生成します（必須：ガラス風サイドバー、背景のオーブ、折りたたみ可能な mind map、サイドバーのフッターに明暗切り替えボタン＋FOUC 対策、13″向けのコンパクトな文字サイズ、skip-link/focus ring、フッターにファイル自身の絶対パスを表示）。内容は各 skill が実行する正確なフローとします：各 skill を1つのノードとし、辺を skill → 成果物 → 次の skill とする（connector は JS で getBoundingClientRect から描画し、resize 時に再描画 — 座標をハードコードしない）。分岐ごとの実行順序を示し、各ノードに呼び出しコマンド＋成果物＋落とし穴を1行で記載します。用語には括弧内で説明を付けます。納品前に実際にブラウザーで開いて（または /playwright-verify を実行して）確認してください。コードを読むだけでは不十分です。
12. adapt-modes ゲート — bundle はゴールではありません。ユーザーに判定を1つ提示します：統合（コード／自分たちの skill に書き換える）· 外部取得（pointer ＋ pin）· 所有権付き組み込み（vendor）· 取得しない（すでに何がカバーしているか、path を記載）。バイト数ではなく、意思決定にかかるコストの軸 — 使用1回あたりの agent 呼び出し数、LLM なしでコードを生成できるか — で比較します。統合／所有権付き組み込みと判定した場合は、scaffold の前に確認してください。

ブランチ

ID	種類	条件	動作	スキップ／失敗	再合流
B01	user_optional	--name <prefix> または --humanize	Naming 表に従って名前を付けます。--humanize の場合は先に重複を確認します	重複 → デフォルトに戻し、その旨を明記します	W05
B02	capability_optional	マシンに実際の統合版がすでにある（別プロジェクトで設定をコミット済み）	それを読み取り、クローン内の fixture より優先します。実際の版で問題を再現します	存在しない → スキップします	W04
B03	conditional_required	rheinmir/dym にリポジトリの bundle がすでにある	再実行せず、取得します（npx skills add rheinmir/dym または clone）	user が再実行を希望 → W02	終了
B04	user_optional	bundle 完了後、共有／使用を希望する	dym-sync.py で lint/index/install/check/push を実行します。または hub をその場で symlink します。または sub-skill をメインリポジトリに昇格させます	gh がない → push を停止します	終了

検証と停止

workflows.md の「検証方法」表では、各主張を file:行／実際の実行ケース／rc に結び付けます。なければ「未検証」と記載します。python3 harness/scripts/dym-sync.py lint が成功すること（bundle は SKILL 形式、hub は domains: を持つこと）。flow.html は実際に開く必要があります。adapt-modes の判定で停止します。scaffold は user の承認後にのみ行います。

例

• 成功例： /doyourmagic https://github.com/Rheinmir/setup → sandbox を clone し、installer と実際の --help を読み、汚れた／クリーンな入力に対して validator を実行して rc を記録 → hub dym-setup + 6 個の sub-skill、30 行の検証表を含む workflows.md、実際に開いた 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 だけを .claude/skills/ に symlink します → context を消費するのは description の1行だけです。子 workflow の本文は、user が /<hub> <slug> と入力したときにのみ読み込まれます。これは /fdk の「1つの名前の hub、範囲を説明するもの」であり、N 個の skill を context に散在させるものではありません。
• Sub-skill は実際の SKILL.md（doc ではありません）です。ディレクトリごとメインリポジトリの skills/ にコピーするだけで、npx skills add でインストールできる skill になります。
• NN-*.md は残しません。実行可能な内容は sub-skill の Steps に配置し、情報源を1つにします。別の doc 版を並行して置いて内容が乖離することもありません。

参考 — Naming — 3つのモード。使用したモードを workflows.md に記録

モード	Hub	Sub-skill	使用する場面
デフォルト	dym-<repo>	dym-<repo>-<slug>	user が何も指定しない場合。重複せず、名前を見れば由来がわかります。昇格時に名前を変更します
--name <prefix>	<prefix>	<prefix>-<slug>	user が自分で名前を指定する場合
--humanize	agent が筋肉で打ちやすい短い名前を付けます（例：overstack）	<hub>-<slug>	確定前に ls ~/.claude/skills .claude/skills で重複を確認する必要があります。重複 → デフォルトに戻し、その旨を明記します
<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（context 1行、model-invocable）は 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>/ として push します（PR）。これにより、後続の人は再実行せずに取得できます：npx skills add rheinmir/dym（hub + sub-skill をインストール。project-scope。global の場合は -g を追加）または git clone --depth 1 https://github.com/Rheinmir/dym.git doyourmagic-bundles。新たに /doyourmagic <repo> を実行する前に、そこに bundle がすでにあるか確認してください。

リファレンス — インストール（ローカルで使用）— 1つのコマンドで、必要なときだけ読み込み

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：ブートストラップ + 19 個のルール + 87 個の skill）。hub dym-setup と 6 個のサブ skill（ファイル名は <名前>.skill.md 形式で保存し、loader に誤って skill としてスキャンされないようにしています）、30 行の検証チェックリストを含む workflows.md、flow.html で構成されています。この実行では実際のバグが 5 件見つかり（PR #114〜#117 で修正済み）、これが目指すべき「検証」の水準です。