SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdoyourmagic

doyourmagic

General & other

View repository

Updated 10-16 00:21

About this skill

Skill: doyourmagic

WHAT

Purpose and context

  • Purpose: turn a freshly cloned external repo/tool into a bundle of RUNNABLE workflow skills (hub /dym-<repo> + N sub-skills) along with workflows.md (verification table) and flow.html, every command cross-checked against the code/--help/actually run — then give an adapt-modes verdict.
  • Trigger (when to use):
    • User just cloned/installed an external repo/CLI/tool and wants "how do I actually use this thing" as something typeable, not a README to re-read each time.
    • User says "pull a new repo", "doyourmagic ", "make a workflow for this tool", "generate workflow docs for this repo", "write runnable usage instructions for this repo".
    • Before folding an external tool into project conventions/CI — produce the bundle first so the integration decision is grounded in verified commands, not README paraphrase.
  • Non-goals: do not paraphrase the README; do not modify the clone (read-only); do not scaffold/integrate into the main repo yourself until the verdict is approved by the user; do not promote the hub.

Mental model

clone (sandbox, read-only) → manifest → README = giả thuyết → đối chiếu parser/--help/exit thật → chạy thật (scope pin) → workflow chia theo ĐỐI TƯỢNG → sub-skill + hub → workflows.md + flow.html → verdict adapt-modes → (tuỳ) dym-sync push / install / promote.

Input and output contract

Field Required? Meaning
In external repo/URL tool yes the thing to make a workflow for
In --name <prefix> / --humanize no naming mode (default dym-<repo>)
In real integration on the machine no if present it wins over the fixture in the clone
Out .overstack/doyourmagic/<repo>/skills/<hub>/SKILL.md + <hub>-<slug>/SKILL.md yes hub with domains:; every skill disable-model-invocation: true
Out workflows.md + flow.html yes verification table (claim → file:line / run case / rc); actually open the flow before delivery
Out adapt-modes verdict yes DISSOLVE · PULL OUT · EMBED-OWN · DO NOT TAKE

Rules and capabilities

  • RULE-01 (MUST): Do not paraphrase the README into "runnable" — every command must exist in the manifest scripts / --help actually / argument parser.
  • RULE-02 (MUST): Do not assume exit codes 0/1 — read the literal exit; a tool may use 2 = "has findings" or fail-open 0 when a file is missing, and the caller must branch correctly.
  • RULE-03 (MUST): Do not carry over .github/workflows/*.yml from the tool into a CI skill for consumers — write your own minimal example.
  • RULE-04 (MUST): Chat commands and shell commands do not share a skill.
  • RULE-05 (MUST): Do not run the tool's installer without pinning scope (measured 2026-09-04: npx impeccable install --help actually installed into $HOME 13 directories). Sandbox + HOME isolation + explicit scope flags.
  • RULE-06 (MUST): Read-only with the clone; only write to .overstack/doyourmagic/<repo>/.
  • RULE-07 (MUST): Each sub-skill is self-contained; the hub only reads the exact file being invoked — do not stuff the whole bundle into context.
  • RULE-08 (MUST): flow.html self-contained (no CDN, no local absolute paths), readable in both light/dark, opened via file://.
  • RULE-09 (MUST): Prefer real execution evidence over citations; anything not yet run must be marked "unverified" right there in place.
  • Capabilities: clone + read external repos in an isolated sandbox; run the tool's commands with pinned scope; write only under .overstack/doyourmagic/<repo>/; open the HTML page in a browser to verify; (optional) push the bundle to the shared repo via the sync tool + PR.

Failure boundaries

  • Command cannot be cross-checked against code/--help/actual run → do not write it as "runnable"; record "unverified" in place (partial).
  • Installer cannot pin scope → blocked for that case, do not run.
  • --humanize collides with an existing skill name → fall back to the default mode and state it clearly.
  • Repo rheinmir/dym already has a bundle for the repo → pull it instead of re-running (clarify with the user if they want to re-run).
  • Verdict MERGE/EMBED → stop and ask before scaffolding.

HOW

Main workflow

Step Type Inputs Action Outputs/exit Failure/next
W01 effect repo Clone into the sandbox (step 1); check whether rheinmir/dym already has a bundle clone read-only bundle exists → B03
W02 deterministic clone Manifest first, README is a hypothesis, cross-check parser/--help/exit for real (steps 2–3) list of cross-checked commands cannot cross-check → "unverified"
W03 effect command Actually run in the sandbox, scope pinned; read the real integration build if available (steps 4–5) rc for each case cannot pin scope → skip that case
W04 judgment results Split the workflow by object, finalize names (steps 6–7) list of hubs/slugs name collision --humanize → default
W05 effect workflow Write sub-skills + hub + workflows.md (steps 8–10) bundle on disk dym-sync.py lint red → fix
W06 effect bundle Sinh flow.html theo docs-site-macos, actually open it in a browser (step 11) flow.html verified display error → fix, reopen
W07 judgment bundle Gate adapt-modes: ONE verdict (step 12) verdict MERGE/EMBED → ask before scaffolding

Step-by-step details (source of truth for W01–W07):

  1. Clone into sandbox (scratch dir) — do not explore in place inside the user's project tree. Exploration is read-only with respect to the clone.
  2. Manifest first, prose after: find package.json / pyproject.toml / Cargo.toml / go.mod / installer script BEFORE reading the README — it gives the real install command, entry point/bin, script list.
  3. README/AGENTS.md/docs are hypotheses, not truth. Every command you plan to write out must be checked against the argument parser / --help actual run / literal process.exit(...) sys.exit(...) — read the actual exit code, don't assume 0/1.
  4. Actually run whatever can be run in the sandbox with tightly pinned scope (HOME isolation, --scope=project, --no-verify…): installer, validator on dirty/clean input, odd modes, missing files. Record the rc for each case — the verification table for workflows.md comes from here.
  5. If the machine already has a real integration (config already committed in another project) → read it; it beats the fixture in the clone for "what using it for real looks like". Reproducing the bug on the real one is the strongest evidence.
  6. Split the workflow by OBJECT, not by feature: consumption (using the tool in your own project) vs contribution (modifying the tool itself). Chat commands (/x) and shell commands go in separate skills — mixing them breaks copy-paste.
  7. Finalize the name according to the Naming table (check for duplicates if --humanize).
  8. Write each workflow as a sub-skill .overstack/doyourmagic/<repo>/skills/<hub>-<slug>/SKILL.md:
    • frontmatter name: <hub>-<slug>, description = one sentence saying WHEN to call it + trigger keywords, and disable-model-invocation: true — so that even when the whole bundle is installed via npx skills add (7 skills), no description line stuffs itself into context; it only loads when typed.
    • ## When to use — situation + "why run it / what it produces".
    • ## Steps — copy-pasteable commands, exact paths, expected output/exit codes. For any command actually run, record the measured rc.
    • ## Rules — traps already MEASURED (not guessed), with how to avoid them; a "must not do" carve-out.
    • Self-contained: don't point to files that exist only in the clone; if needed, "if file X is present then…".
  9. Write the 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: table (skill · purpose · branch · invocation command), "suggested run order", "most expensive traps", table "how to verify" (claim → file:line / actual run case / rc), naming mode used, and one-line symlink command (Install section below).
  11. flow.html — generated per skill docs-site-macos (MANDATORY: glass sidebar, background orbs, collapsible mind map, light/dark toggle button in sidebar footer + FOUC prevention, compact 13″ font size, skip-link/focus ring, footer shows absolute path of the file itself). Content = exact flow of skills performed: one node per skill, edges skill → sản phẩm → skill kế (connectors drawn by JS from getBoundingClientRect, redrawn on resize — no hardcoded coordinates), execution order by branch, each node records the call command + artifact + one-line pitfall. Terms glossed in parentheses. Actually open in a browser (or /playwright-verify) before delivery — reading code is not enough.
  12. Gate adapt-modes — a bundle is not the destination. Give the user ONE verdict: DISSOLVE (rewrite into our own code/skill) · PULL OUT (pointer + pin) · EMBED-OWN (vendor) · DON'T TAKE (already covered by something, note path). Compare on the cost decision axis — agent turns per use, can the code be generated without an LLM — not bytes. Verdict DISSOLVE/EMBED → ask before scaffolding.

Branches

ID Kind Guard Behavior Skip / failure Rejoin
B01 user_optional --name <prefix> or --humanize name according to the Naming table; --humanize must be checked for duplicates first duplicate → fall back to default, state clearly W05
B02 capability_optional machine already has a real integration (config committed in another project) read it, prefer it over the fixture in the clone; reproduce the bug on the real version none → skip W04
B03 conditional_required rheinmir/dym already has the repo's bundle pull it in (npx skills add rheinmir/dym or clone) instead of re-running user wants to re-run → W02 end
B04 user_optional after the bundle is done, wants to share/use it dym-sync.py lint/index/install/check/push; or symlink the hub in place; or promote sub-skill to the main repo missing gh → push stops end

Validation and stopping

"how to verify" table in workflows.md: each claim points to file:line / actual run / rc — if missing, write "unverified". python3 harness/scripts/dym-sync.py lint green (SKILL-type bundle, hub has domains:). flow.html must actually be opened. Stop at verdict adapt-modes; scaffold only after user approval.

Examples

  • Positive: /doyourmagic https://github.com/Rheinmir/setup → clone sandbox, read installer + --help actually, run validator on dirty/clean input recording rc → hub dym-setup + 6 sub-skills, workflows.md 30-line verification table, flow.html actually open → verdict (see references/example-setup/).
  • Boundary/failure: tool has npx <tool> install but --help does not list the scope flag → do not run installer (actually installs into $HOME), sub-skill writes "unverified" for the install command along with known pitfalls.

Reference — Output shape (what a finished run leaves behind)

.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 is the only thing symlinked into .claude/skills/ → context only costs one description line; the child workflow body is only read when the user types /<hub> <slug>. This is the "one-name hub, scope description" of /fdk, not N skills scattered across context.
  • Sub-skill is a real SKILL.md (not a doc): copy the whole directory to skills/ of the main repo is what makes it a skill installed with npx skills add.
  • No more NN-*.md: runnable content lives in the sub-skill's Steps — one source, no parallel doc copy to drift.

Reference — Naming — 3 modes, record the mode used in workflows.md

Mode Hub Sub-skill When
default dym-<repo> dym-<repo>-<slug> user says nothing. Never duplicates, name reveals the source; rename at promote time
--name <prefix> <prefix> <prefix>-<slug> user-named
--humanize agent picks a short name typeable by muscle memory (e.g. overstack) <hub>-<slug> must ls ~/.claude/skills .claude/skills check for duplicates BEFORE finalizing; duplicate → fall back to default and say so clearly
<repo> = repo name (last segment of the URL, drop .git), lowercase, - replaces odd characters. <slug> = 1–2 words saying the job (install, ci, contributor), no numbering.

Reference — Sync + routing — harness/scripts/dym-sync.py (stdlib, 0 tokens)

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 must declare domains: [a, b] in frontmatter — /dym (1 context line, model-invocable) reads the domain table to pick the bundle itself: chart → lieflat-charts, frontend → impeccable… Hub and sub-skills remain disable-model-invocation, loaded only when called.

Reference — Bundle store that has run — rheinmir/dym

After each run, dym-sync.py push <repo> pushes .overstack/doyourmagic/<repo>/ to https://github.com/Rheinmir/dym as <repo>/ (PR) so the next person pulls it instead of re-running: npx skills add rheinmir/dym (install hub + sub-skills, project-scope; add -g for global) or git clone --depth 1 https://github.com/Rheinmir/dym.git doyourmagic-bundles. Before running /doyourmagic <repo> new: check whether the bundle is already there.

Reference — Install (in-place usage) — one command, loads only when needed

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

Only the hub goes into context. Type /<hub> to see the slug table, /<hub> <slug> to run a workflow. If you want to call /<hub>-<slug> directly, symlink that exact directory in addition — each extra symlink adds one more context line, so weigh it carefully.

Reference — Promote to main repo (skill installed via npx)

The path /fdk already exists, don't spawn a tool:

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ả>"

Edit name: in the frontmatter to match the new name; keep the description trigger. The hub does NOT promote (it only makes sense alongside the bundle).

Reference example

references/example-setup/ — one real run of this skill on rheinmir/setup (overstack: bootstrap + 19 rules + 87 skills): hub dym-setup + 6 sub-skills (child files stored as <tên>.skill.md so the loader doesn't mistakenly scan them as skills), workflows.md with a 30-line verification table, flow.html. That run found 5 real bugs (already patched in PR #114–#117) — that is the level of "verification" that needs to match.