embedded-captions: shipped files point at author-only ~/Downloads paths, and references/test-set.md is orphaned #3219

Filing under the feature form because blank issues are disabled and the bug form requires a minimal-reproduction repo — there is nothing to reproduce here, the problem is in files the skill ships. Happy to refile if you'd rather have it as a bug.

Problem

skills/embedded-captions is distributed to other machines via npx hyperframes skills, but parts of it point at directories that only exist on the author's machine. 12 references to ~/Downloads, across 8 files, spanning 10 distinct paths. None of them exist on a clean install.

One of those is fine and I'm not proposing to change it: ~/Downloads/hyperframes (SKILL.md:251, scripts/matte.cjs:26, scripts/measure-layout.cjs:22, scripts/render-and-composite.sh:17) is the documented last resort in a real resolution chain — HYPERFRAMES_ROOT env → in-repo path → ~/Downloads/hyperframes — and render-and-composite.sh implements it properly. That's a sensible default, not a leak.

The other 8 references have no fallback of any kind.

themes/PORTING.md — the porting procedure is unrunnable off the author's machine

Six author-only directories, five of them load-bearing steps in the procedure:

Line 45 is the one I'd flag hardest: it points at a normative contract document (≤ DUR scheduling) that ships nowhere. A reader following PORTING.md is told to consult a spec they cannot obtain.

SKILL.md:177 and dna/README.md:17 — the retired template library

The retired 54-template library lives outside the skill at ~/Downloads/embedded-captions-archive/standard-templates-54/

Stated as a fact about where something lives. For anyone but the author, it doesn't.

references/test-set.md — orphaned and pointing at a corpus nobody has

Two problems at once:

1. Referenced from nowhere. I grepped all 140 shipped files: zero references to test-set outside the file itself. Nothing in SKILL.md, no other reference, no script. (Worth noting I checked the whole tree rather than just SKILL.md — typographic-moves.md looked orphaned too until I found it linked twice from references/composition-craft.md. test-set.md really is unreachable.)
2. Line 9: All in ~/Downloads/heygen_relevant_videos/ — so even when found, the test set can't be run.

Proposed solution

Different answers for different items, and the right destinations are yours to pick — I don't know what these directories contain:

• themes/PORTING.md — either vendor the demo/contract material into the skill (at minimum cap_fx3/CONTRACT.md, since it's normative), or replace the paths with a documented env var + resolution chain like the one ~/Downloads/hyperframes already has. Failing both, mark the file explicitly as internal/author-only so readers don't follow a dead procedure.
• The retired 54-template library — if it's genuinely retired and not needed, say so without the path. If it's still consultable, it needs a real home (release asset, separate repo, or in-tree).
• references/test-set.md — delete it, wire it up from SKILL.md, or move it out of the distributed tree. As-is it's dead weight that also can't be executed.

Alternatives considered

Sending a PR instead. I didn't, because every fix here needs a decision only you can make — where the archive should live, whether the demos are vendorable, whether the test set should exist in the distribution at all. Mechanical substitution on my side would just be guessing. Happy to send a PR once you've picked a direction.

Additional context

Found while auditing skill files for the Claude Code skill-listing budget, not while using the skill — so I haven't hit a runtime failure from this; it's a read of the shipped tree.

Two things that came up in the same pass and are not problems, recorded so they don't get re-flagged:

• SKILL.md:177 says "_motion.md remains in-skill." It does — at modes/standard/_motion.md. Not a broken reference.
• packages/cli/dist/cli.js resolves correctly via the chain described above.

Credit where due: embedded-captions was the best-factored skill in the set I looked at — 140 files, 16 references, 7 scripts, and zero duplicated content, which is more than I can say for a couple of its siblings (#3218, #3117). These paths are the one thing that doesn't travel.