super-skill - one best-of skill from an analysed topic

topic-analysis.json says what many skills for one topic do and which does each part best. Your job: produce ONE new skill that keeps the best of them and drops the rest. More is not better: every extra step, check or option costs the future reader attention, so an element earns its place only if a source did it clearly better than the alternatives or no source did it at all.

The analysed skills are the corpus (same idea as corpus-builder: the corpus is the quality ceiling). If the analysis is thin, say so instead of padding.

Invoked as /super-skill [path/to/topic-analysis.json] [--out <dir>]. Defaults: ./topic-analysis.json, output ./super-skills/<topic-slug>/ (slug = lowercase, hyphenated topic). Helper: scripts/check.py (stdlib Python; run with python3 -I).

Step 1 - Read and gate the corpus

1. Read the file. If missing, unreadable or not JSON, stop politely: say what is missing and point to the topic-analysis skill (/topic-analysis <topic>). Do not guess a corpus.
2. Run python3 -I <SKILL_DIR>/scripts/check.py input <file>. Invalid (missing keys, duplicate or dangling blob_sha) means a corrupt analysis: stop, report the failures, ask for a re-run of topic-analysis. Schema: references/input-schema.md.
3. Corpus gate - proceed only if all hold, else name the gap and ask whether to continue:
   • at least 2 analysed skills (one skill leaves nothing to combine)
   • synthesis.best_in_class is non-empty (otherwise there is no backbone to choose)
   • at least one source has a non-empty sop
   • selection.skipped is shown to the user (they may want a skipped skill back in)

Step 2 - License gate

Decide per source what you may take. Full rules and edge cases: references/licensing.md.

python3 -I <SKILL_DIR>/scripts/check.py license <file> --fetch

It classifies each source and also reads the SKILL.md's own license: frontmatter, because a permissive repo can still ship a file that reserves its rights; the stricter signal wins.

"Ideas only" is a working discipline: write from the topic-analysis fields (sop, patterns, validations) and your own understanding, in your own words and structure. Do not paste the source into context and reword it. Record every decision now; PROVENANCE.md needs them.

Step 3 - Design

Work from synthesis, not from re-reading every source.

1. Backbone. Choose the SOP from best_in_class and sop_variants: the variant whose steps cover the topic's real task from input to verified output. If no variant covers it end to end, graft the strongest variant's tail onto the best head. Break ties with ai_style_score (lower), stars, then support_dirs (scripts/references present).
2. Validations. Walk validations_ranked top-down. Include a check only if it catches a failure the backbone would otherwise ship, and say what the check cannot see. Drop checks that duplicate each other or only fit a niche the topic does not centre on; list those under "left out" with the reason.
3. Inputs and outputs. Start from inputs_union/outputs_union, keep only what the SOP reads or produces, make each optional input default to something sensible. Fewer knobs is better: a default plus one escape hatch.
4. Gaps. For each synthesis.gaps item decide: cheap to fill (a sentence or a short step - fill it, mark it new) or expensive (record it as an open gap, do not bluff).
5. Route out. Name what the super skill is not for, and which sibling to use instead.
6. Cite as you go. Keep a ledger of element -> source(s) | new. An element with no source and no new mark does not go in.

For a prose template of the design table, see references/provenance-format.md.

Step 4 - Write the super skill

Create the output folder with SKILL.md, references/ as needed, PROVENANCE.md, evals/evals.json. Follow skill-creator conventions:

• Frontmatter name (kebab-case, equals the folder) and description. The description is the trigger: what it does plus the contexts and phrases that should fire it, a little pushy, under 1024 characters, no body-only information.
• Body under 500 lines, imperative, one step per decision, explain why a rule exists instead of shouting MUST. Push detail (long recipes, tables, per-tool notes) into references/ and say in SKILL.md when to read each file. Add a table of contents to any reference over 300 lines.
• Scripts only where a source proved deterministic code is worth shipping and its license allows it; otherwise write your own small helper or leave it out.
• Adapted text from a permissive source gets a one-line credit next to it. Ideas-only sources get no text, but are still cited in PROVENANCE.md.
• Do not copy the source skills' structure wholesale; the super skill's shape follows the backbone you chose.

Step 5 - Provenance and evals

PROVENANCE.md (format in references/provenance-format.md) holds, in order: sources and license decisions (one row each, including the skipped ones), the element ledger (every included element -> blob_sha + repo + skill_url, or new), what was left out and why, open gaps, the output license, and the section "How to prove it beats the best single source".

evals/evals.json - 5 to 8 realistic prompts for the topic, the kind a real user types (file names, backstory, a casual register), covering each major branch of the SOP plus at least one edge case the validations exist for and one near-miss that should route elsewhere. Each has expected_output and 3 to 6 assertions: objectively checkable behaviours (which tool was chosen, which check ran, what the final message states), not vibes. Schema as in skill-creator (id, prompt, expected_output, files, assertions).

Proof protocol to write into PROVENANCE.md, per skill-creator's eval approach:

1. Baseline = the source skill that appears most often in best_in_class (tie: more stars).
2. For each eval, run it with the super skill and with the baseline, same prompt, in the same turn, saving outputs side by side; grade the assertions for both.
3. Ship only if the super skill wins or ties on every eval. A loss on any eval means find the element that is missing or wrong, fix it, rerun everything.
4. Also run a no-skill baseline once, to confirm the evals actually discriminate.

The baseline runs need the baseline skill's license to allow running it locally, which any license does; they do not copy its text into the super skill.

Step 6 - Check, then report

python3 -I <SKILL_DIR>/scripts/check.py output <out-dir> --analysis <file> --fetch

It verifies frontmatter and line count, that referenced files exist, that evals.json parses with 5-8 evals, that every analysed blob_sha appears in PROVENANCE.md, and that no 8-word run of text from an ideas-only source appears anywhere in the output. Fix every FAIL before reporting. If a source could not be fetched the overlap check is skipped for it: say so.

Then tell the user, briefly and in this order:

1. Taken from where - element -> source, grouped by source.
2. Left out and why - including skipped and ideas-only sources.
3. License decisions - one line per source, and the output license.
4. New - gaps you filled; open - gaps you did not.
5. Next step - run the evals (super skill vs baseline); it ships only if it wins or ties on every eval. Offer to run them.

Rails

• Never write outside the output folder; never overwrite an existing folder without asking.
• Never present an unrun eval as passed. "Written, not yet run" is a fine status.
• Unknown license stays unknown. Do not upgrade it on a hunch.
• A source you did not use is still listed, with the reason.
• If the user wants a union ("just include everything"), say once what it costs (longer, slower to trigger, contradictory steps), then follow their call.