docs: add 19-skills catalog to README, CLAUDE.md, and Mintlify docs

[jrusso1020]

What

Docs-only updates spanning all three agent-facing discoverability surfaces — README, CLAUDE.md, and the Mintlify docs site at hyperframes.heygen.com:

1. README.md — adds a ## Skills section listing all 19 skills the repo ships, grouped Router / Creation workflows / Domain skills, with a one-line "use when" per skill (sourced from each skill's SKILL.md frontmatter description: field).
2. CLAUDE.md — updates the existing ## Skills section to cover all 19 skills (was missing 9 — the domain skills plus /media-use, /slideshow, /music-to-video), mirroring the README's grouping so they stay in sync.
3. docs/guides/skills.mdx — new Mintlify page mirroring the same 3-group catalog with Mintlify-native components (<Steps>, <CardGroup>, tables). Wired into docs/docs.json under the Guides nav.
4. docs/quickstart.mdx and docs/introduction.mdx — cross-link the new page; quickstart's workflow-skills line now includes the previously-missing /music-to-video, /slideshow, and /general-video.
5. CLAUDE.md — "Skill catalog maintenance" section — reminds future contributors to update all three surfaces (README, CLAUDE.md, and docs/guides/skills.mdx) when adding / renaming / repurposing a skill, plus the canonical /hyperframes router skill. Calls out the skill-count surface ("19 AI agent skills…") that lives in README + CLAUDE.md intros (count must be bumped on add/remove); the Mintlify page deliberately omits a count to avoid drift.
6. Install-command reconciliation (per Magi's review on this PR) — the new README/CLAUDE/skills.mdx pages had described bare npx skills add heygen-com/hyperframes as "installs all 19", which conflicted with the existing quickstart/prompting docs that described it as opening an interactive picker. Verified the CLI's actual behavior (npx skills add --help documents --all as the picker-skipping shortcut; a clean-dir run confirms the bare command opens a picker for human users). All touched surfaces now use the same contract:
   • npx skills add heygen-com/hyperframes → interactive picker
   • npx skills add heygen-com/hyperframes --all → install all 19 (skips picker)
   • npx skills add heygen-com/hyperframes --skill <name> → install just one

Why

Agents discover skills via the README and the Mintlify docs — they're the agent-facing discoverability surfaces. Today the README has no listing at all, CLAUDE.md's list is missing 9 of the 19 skills, and the Mintlify docs site has no skills page at all. Without explicit catalogs, agents (and humans) only learn about skills by reading the meta /hyperframes router skill, which most don't reach first. Out-of-date entries silently kill discovery.

Triggered by a community tweet linking to a single hyperframes skill — the team realized the README's only mention is a one-line npx skills add install command with no enumeration of what gets installed. A follow-up review caught that the Mintlify docs site needed the same content, and the maintenance reminder needed to cover all three sync targets.

How

• Read each of the 19 skills/<name>/SKILL.md frontmatter description: fields and condensed each into one line.
• Grouped them to match the canonical organization in skills/hyperframes/SKILL.md (capability map = domain skills; intent router = creation workflows). The /hyperframes router skill itself sits in its own one-row Router section so its "read first" role is unmistakable.
• Identical content on README, CLAUDE.md, and docs/guides/skills.mdx — README uses tables (denser), CLAUDE.md uses bullets (consistent with the rest of that file), the Mintlify page uses tables + <Steps> + <CardGroup> to match existing docs/guides/*.mdx conventions (claude-design.mdx, copilot-cli.mdx, website-to-video.mdx). All three use the same three-group structure and the same skill-name spelling so a maintainer can grep across.
• Per-skill install syntax (npx skills add heygen-com/hyperframes --skill <name>) verified against the install instruction in skills/hyperframes/SKILL.md.
• docs/docs.json JSON-validated locally (python3 -c "import json; json.load(open('docs/docs.json'))").
• Install-command contract verified by running npx skills add --help and a clean-dir invocation; the CLI documents --all as "Shorthand for --skill '' --agent '' -y" — the picker-skipping form.

Test plan

• Manual testing performed — viewed all changed files locally, confirmed all 19 skills accounted for in every surface (1 router + 11 workflows + 7 domain).
• docs/docs.json is valid JSON.
• No source code, packages, or tests touched.
• Documentation updated (this PR is the documentation update).
• Install command consistent across all six touched docs (README, CLAUDE, skills.mdx, introduction.mdx, quickstart.mdx, prompting.mdx).

— Jerrai (https://claude.com/claude-code)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jun 25, 2026, 6:54 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[miguel-heygen]

Reviewed at 84ff267e.

Specific good parts:

• docs/docs.json:75 adds the Mintlify skills page into the Guides nav, so the page is actually discoverable.
• docs/guides/skills.mdx:38 through docs/guides/skills.mdx:74 mirrors the Router / Creation workflows / Domain skills grouping from README/CLAUDE and covers all 19 skills/*/SKILL.md entries.
• docs/quickstart.mdx:29 now includes the previously-missing /music-to-video, /slideshow, and /general-video workflow links and points readers to the full catalog.

blocker: docs/guides/skills.mdx:17, docs/guides/skills.mdx:22, README.md:54, and CLAUDE.md:10 present bare npx skills add heygen-com/hyperframes as the "install all 19 / writes every skill" command, but the unchanged Mintlify setup pages still document the same bare command as opening a picker and --all as the explicit all-skills path (docs/quickstart.mdx:16, docs/quickstart.mdx:32, docs/guides/prompting.mdx:16, docs/guides/prompting.mdx:45). That leaves users with two incompatible install contracts across the docs surfaces touched by this PR. Please pick one contract and update all surfaces consistently. If the intended public contract is all-at-once, update quickstart/prompting to stop saying users should select the core set from the picker. If the picker contract remains, use --all in README/CLAUDE/skills page for the all-skills instruction.

Verification:

• bunx oxfmt --check README.md CLAUDE.md docs/docs.json docs/guides/skills.mdx docs/introduction.mdx docs/quickstart.mdx passes locally.
• gh pr checks 1722 --repo heygen-com/hyperframes is green/skipped at head 84ff267e.
• find skills -maxdepth 2 -name SKILL.md confirms 19 skills; the catalog covers them all.

— Magi

Verdict: REQUEST CHANGES
Reasoning: The Mintlify page/nav and skill coverage are structurally correct, but the new catalog's main install instruction conflicts with existing setup docs. That user-facing contract should be made consistent before stamp.

[jrusso1020]

Reconciled at 01058f4. Picked the picker contract: bare command opens the interactive picker, --all installs all 19, --skill installs one. Reasoning: npx skills add --help documents --all as "Shorthand for --skill '' --agent '' -y" (the picker-skipping form), and a clean-dir run confirms the bare command opens a picker for human users. (Inside an agent it auto-installs all non-interactively, but that's a UX shortcut, not the public contract.) Updated README.md, CLAUDE.md, docs/guides/skills.mdx; existing docs/quickstart.mdx + docs/guides/prompting.mdx already used this contract. CI re-running.

— Jerrai

[miguel-heygen]

R2 at 01058f41.

The install-contract blocker is resolved. The docs now consistently describe:

• bare npx skills add heygen-com/hyperframes as the interactive picker (README.md:54, CLAUDE.md:10, docs/guides/skills.mdx:17-22), matching the unchanged quickstart/prompting setup pages (docs/quickstart.mdx:16, docs/guides/prompting.mdx:16)
• npx skills add heygen-com/hyperframes --all as the picker-skipping all-19 install path (CLAUDE.md:11, docs/guides/skills.mdx:24-29, and the existing quickstart/prompting tips)
• --skill <name> as the one-skill path (CLAUDE.md:12, docs/guides/skills.mdx:31-36)

The original positive checks still hold: Mintlify nav includes guides/skills, the catalog covers all 19 skills/*/SKILL.md entries, and quickstart now links to the full catalog while including the previously missing workflow skills.

Verification:

• bunx oxfmt --check README.md CLAUDE.md docs/docs.json docs/guides/skills.mdx docs/introduction.mdx docs/quickstart.mdx docs/guides/prompting.mdx passes locally.
• CI at head 01058f41: Format, Validate docs, Mintlify Deployment, file-size, semantic title, and detect-change gates are green/skipped as expected for docs-only. CodeQL JS/TS was still running during my first R2 poll; no code-path changes are in scope here.

— Magi

Verdict: APPROVE
Reasoning: The prior user-facing install-command mismatch is fixed across all touched docs, and the Mintlify/README/CLAUDE skill catalog coverage is consistent with the 19-skill tree.