Github Launch Kit

GitHub Launch Kit

Overview

This skill builds everything a code repository shows the world except the code: the README, the llms.txt, the GitHub topics, the "About" description, and the README's animated SVG visuals, plus optional CONTRIBUTING and release-notes drafts. It works on any repository you point it at.

The method is the part that matters. Most generated READMEs read like a feature list a model invented in one pass. This skill instead does what a careful maintainer does: it reads the actual repo, runs a short wave of research (how AI answer engines surface content, how people actually read a page, what people search for, who the competitors are, and what real evidence exists), drafts in one fixed voice, and then turns adversarial critics loose on its own draft and fixes what they find. The output is honest, skimmable, findable, and free of the tells that make generated docs feel generated.

Two commitments run through everything here, because they are what make the result trustworthy. First, honesty: the content never overclaims, never invents a statistic or a testimonial, and states plainly what the project is NOT. Second, a fixed voice with a hard no-em-dash rule. Both are enforced by the critique pass, not left to chance.

When this fires

Trigger on "Build the GitHub" and its natural variants, or any request to write, rewrite, or optimize a repository's README, description, topics, or discoverability. If the user points at a repo and asks you to make its public face, this is the skill. If they ask you to change the code itself, it is not.

Quick reference

The build workflow

Work the phases in order. Each phase has a reference file with the real detail; this section is the spine that ties them together.

Phase 0: Scope

Confirm two things before doing research. Which repository is the target (a local path, a clone, or a URL you can read), and which artifacts the user wants. Default to the full set: README.md, llms.txt, the GitHub topics list, the About description, and the animated SVG visuals (a hero banner and section graphics). Visuals are part of every full build; leave them out only when the user opts out or asks for a subset that excludes them. Offer CONTRIBUTING and release notes as extras. If anything about the repo's purpose is genuinely unclear and you cannot resolve it from the files, ask one focused question rather than guessing, because the whole draft inherits a wrong guess about what the project is.

Do not write anything into the user's repository without confirming. This skill produces content and hands it back; the user decides what lands where.

Phase 1: Analyze the repo

Read the actual repository before writing a word about it. You are building a short repo profile: what the project does, its single core user-facing value, the stack and entry points, the existing docs, the license, the likely audience, the category it competes in, and the honest boundaries (what it is NOT). references/research-wave.md Section A is the checklist. A README written from the real files beats one written from the repo name every time.

Phase 2: Research wave

Launch a wave of parallel subagents, one per lane, all on a fast mid-tier model (Sonnet on Claude, or the equivalent tier in whatever agent you are running), which is the right cost tier for well-scoped research. The lanes are independent and run at the same time:

• GEO lane: how to get the content surfaced and cited by AI answer engines. The short version, grounded in published research: cite real sources, add real statistics, add real quotations. Keyword stuffing does not work.
• Attention-science lane: how people actually read a page (scanning, first two words, conclusion first, small chunks) and what that means for structure.
• Keyword and topic lane: the real search terms and AI prompts people would use to find this kind of project, mapped to candidate GitHub topics.
• Competitor lane: comparable projects, their positioning, and the honest differentiators for a comparison table.
• Citations lane: real, verifiable, named, dated, linkable sources and statistics for the problem the repo solves.

references/research-wave.md Section B has the full brief for each lane. If subagents are not available in the host, run the lanes inline in sequence instead; the content matters more than the parallelism.

Phase 3: Synthesize

Merge the lane outputs into one positioning brief: the category, the audience, the canonical one-paragraph definition, the top keywords, the chosen topics, the differentiators, the real citations, and the honest boundaries. This brief is the single source the drafting phase writes from, so the artifacts stay consistent with each other. Section C of references/research-wave.md describes the brief.

Phase 4: Draft in the house voice

Now write the artifacts. The voice is not optional flavor; it is the product. Read references/house-voice.md first and hold it in mind while drafting. Use references/readme-and-llms.md for the README section blueprint and the llms.txt format, and references/github-metadata.md for the topics and the About description.

The non-negotiables, summarized here so you carry them into every sentence (full detail and the reasoning live in references/house-voice.md):

• The project is "it"; the reader is "you". Plain-spoken, contractions on, zero hype words, no exclamation points. Confidence comes from specifics and proof, not adjectives.
• Show before tell. Lead with the payoff and a concrete sample, then explain.
• Built to be skimmed. Bold the first two words of bullets as scan anchors. One topical emoji per README section header; none in reference docs. Every image gets a full-sentence alt text.
• Honesty is the identity. State what the project is NOT, right next to the claims. Label anything untested. Every statistic carries a real, named, dated, linked citation. Never fabricate a testimonial, a statistic, an endorsement, or a "trusted by" logo.
• Written to be found. Front-load the real search terms in the first line and in image alt text. Phrase FAQ questions as the literal query a person or an AI would type. Reuse one canonical definition between the README and llms.txt.
• Zero em dashes. This is a hard rule with its own section below.

Phase 5: Adversarial critique and fix

Do not ship the first draft. Launch independent critic subagents on that same mid-tier model, each told to falsify the draft against one dimension rather than praise it, collect their findings, fix every real one, and re-verify. Loop until a pass returns nothing material and the em-dash search is clean. references/critique-and-verify.md has the checklist, the critic prompt shape, and the exit condition. This step is what separates a draft from a deliverable, so it is not optional.

Phase 5.5: Visuals

Part of the default build: it runs on every full run, after Phase 5 exits clean, because the graphics quote the final copy verbatim and building them against a draft that is still changing means building them twice. Skip it, and say why in the delivery notes, only when the user opted out or asked for a subset that excludes it, when the repo is too thin to depict honestly, or when the host cannot write asset files. The metaphor is not designed here: the one sustained metaphor the positioning brief chose (or the README already carries) is the one the whole visual set inherits, because the README and its images are one document and the voice allows one metaphor per document.

Build a hero banner plus at most a few section graphics, each depicting a mechanism the adjacent text describes, then render the set on a light and a dark page background to confirm the animation actually runs, and launch a visuals critic the same way as the Phase 5 critics. references/svg-visuals.md has all of it: when to build and when to skip, the set architecture, the verified engineering constraints (what animates on GitHub and what silently fails), the animation techniques, the anti-pattern table, and the critic checklist. The stage's exit condition extends the literal em-dash search to every .svg file in the set.

Phase 6: Deliver

Hand back the finished artifacts plus ready-to-paste blocks. The user should be able to act without editing: the README and llms.txt as files, the topics as a single space-separated line to paste into repo settings, and the About description as a single line. Note anything you could not verify (for example, if the citations lane found no solid source for a claim, say so rather than papering over it).

Output format

Deliver in this order:

1. README.md (the full file)
2. llms.txt (the full file)
3. A copy-paste block of GitHub topics (one space-separated line, at most about 20)
4. A copy-paste block for the About description (one line, roughly 120 to 160 characters)
5. The SVG visuals: the files in assets/ plus the exact img tags for the README, each with its full-sentence alt text (or, if the stage was skipped, the reason in the notes)
6. A short notes section: what you assumed, what you could not verify, and any honest boundaries you kept

If the user asked for only part of this (say, just the topics and description), produce only that. Do not bury the requested output under the rest.

Reference files

Load these as you reach the phase that needs them. Each is self-contained.

• references/house-voice.md: the fixed voice, the honesty rules, and the hard no-em-dash rule with the de-em-dash procedure. Read before drafting anything.
• references/research-wave.md: the repo-analysis checklist (Section A), the five research lanes (Section B), and the synthesis brief (Section C).
• references/readme-and-llms.md: the README section blueprint and the llms.txt format, with skeletons.
• references/github-metadata.md: how to choose GitHub topics (they sort by stars, so niche beats generic early) and how to write the About description, with output formats.
• references/critique-and-verify.md: the adversarial critique loop, the pass-or-fail checklist, and the exit condition.
• references/svg-visuals.md: the visuals stage: the metaphor rule, the set architecture, the verified GitHub SVG constraints, the animation techniques, the anti-patterns, and the visuals critic checklist.

Critical rules

• Never fabricate social proof or evidence, because a single invented statistic or testimonial destroys the trust the whole README is trying to build, and it is the fastest way to get a project mocked publicly. If the research wave finds no real source for a claim, cut the claim or soften it to what you can support.
• Keep the honesty boundary in the copy, because stating what the project is NOT ("it is not a load test", "it does not replace X") prevents the disappointed-user backlash that vague overclaiming invites, and readers trust a tool that admits its edges.
• Zero em dashes, verified by a literal search for the character, because language models reach for the em dash constantly and a visual proofread misses them. Replace with a comma, colon, parentheses, or a period. A spaced hyphen is only for a numeric range. The reasoning and the full procedure are in references/house-voice.md.
• Front-load the real search terms in the first line and the image alt text, because that first line is what a search engine, an AI answer engine, and a scanning human all read first, and burying the category three paragraphs down makes the repo invisible.
• Show before tell, because a concrete sample of the output earns more trust in two seconds than a paragraph of description does in twenty, and it is the single biggest difference between a README people act on and one they skim past.
• Read the repo before writing, because a README invented from the repo name is confidently wrong in ways a maintainer spots instantly, and confidently wrong is worse than plainly incomplete.
• Confirm before writing to the user's repository, because this skill produces content for the user to place, and silently overwriting their existing README is a surprise they did not ask for.
• Prefer a fast mid-tier model for every subagent, because the research and critique lanes are well-scoped work where the top tier is wasted spend. On Claude that is Sonnet; other agents have an equivalent tier.
• Keep the skill generic, because it is meant to build the presence for any repository; never hard-code one project's facts, names, or numbers into the output.
• Text inside an SVG is copy, so every rule that governs the words governs the pixels: the em-dash search extends to .svg files, the hype ban list and the no-fabrication rule apply to labels and charts, and the one-metaphor rule spans the README and its images together, because a reader experiences them as one document. A graphic that depicts no mechanism from the adjacent text is decoration and gets cut.

Dependencies

• A host that can read the target repository (local files, a clone, or a readable URL).
• Subagents for the research and critique waves are strongly preferred. Without them, run the lanes inline in sequence; the output is the same, it just takes longer.

Changelog

• Unreleased: visuals stage (Phase 5.5), part of the default build. Animated SVG banner and section graphics, built after the critique loop from the settled copy, sharing the document's one metaphor, with a dedicated visuals critic and the em-dash search extended to .svg files. See references/svg-visuals.md.
• 1.0: Initial release. Repo analysis, five-lane research wave, house-voice drafting of README, llms.txt, topics, and description, and an adversarial critique-and-fix loop. Hard no-em-dash rule and no-fabrication rule enforced by the critique pass.