repo-pitch
Skill0 starsChanged 49 days agoMITView on GitHub
Use when writing or fixing the one-line description a repo shows the world — a GitHub About box, a README's opening sentence, a package summary on PyPI or npm, a Show HN title, a plugin or extension listing — or when those have drifted apart and you want them to be one string again. Also for judging a draft one-liner before adopting it: what length actually fits each surface, why a list of features reads as a non-answer, and which style rules are real versus somebody's taste. Checks that a pitch is well formed; it does not score whether the project is appealing, and it does not write marketing copy.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- db-defaults-taudeltaSkill
- invoke-task-conventions-taudeltaSkill
- mcp-python-conventions-taudeltaSkill
- mcp-server-shippingSkill
- plan-conveyorSkill
- polite-mcp-conventions-taudeltaSkill
- python-conventions-taudeltaSkill
- python-refactor-auditSkill
- python-testing-conventions-taudeltaSkill
- release-heraldSkill
- research-librarySkill
- session-bash-auditSkill
- session-harvestSkill
- skill-authoring-taudeltaSkill
- skill-fitnessSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Every number below is sourced in references/measurements.md — the two corpora and how they were drawn, the full distributions, the platform …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The one line a stranger reads first
A repo's short description is one string with several deploy targets, not several strings.
standard-readme has required exactly that since
2017 — the README's short description must match the package manager's description and
GitHub's description — and almost nobody does it: of 17 well-known projects sampled, 4 matched
README to GitHub; of 13, 5 matched GitHub to their registry.
So the work is usually not writing a new pitch. It is finding the one you already have, deciding which wording wins, and putting it on every surface.
Every number below is sourced in references/measurements.md — the
two corpora and how they were drawn, the full distributions, the platform limits with the code each
was read from, and the two negative results that bound what this skill may claim.
What this skill reads, runs and writes
- Reads: a README path you name; this repo's own
scripts/.driftadditionally reads a GitHub repo's description and a package's summary on PyPI or npm. - Runs:
gh repo view <repo> --json description, underdriftonly. Nothing else shells out. - Writes: nothing. Every command prints; none edits a README, sets a description, or calls
any write API. Applying a fix is your edit, or your
gh repo edit, taken deliberately. - Network:
driftonly —api.github.comthroughgh, pluspypi.orgorregistry.npmjs.orgfor the registry summary. Every other command is offline.
Run the script
scripts/pitch.py owns every threshold and every rule. Stdlib only, so it runs
by path.
python3 <path>/pitch.py check "<the pitch>" --name <project> --surface github
python3 <path>/pitch.py check "<the pitch>" --explain # what the levels mean, and what it cannot see
python3 <path>/pitch.py surfaces # every length budget, with its source
python3 <path>/pitch.py readme README.md # the short description, as a reader finds it
python3 <path>/pitch.py drift --readme README.md --repo <owner>/<name> --pypi <package>check exits 1 on a blocking finding, drift exits 1 when the surfaces disagree, so both work in a
gate. Every command takes --json.
A rule may block only where a controlled corpus clears it
This is the part worth understanding, because it is what separates the checks from somebody's taste.
Each rule carries two rates: how often it fires across 856 top developer-tool repos, and how often across 85,842 Debian package synopses — a corpus governed by written rules and machine-checked by lintian. The second number is a false-positive rate. A rule that fires on real linted synopses is a rule about style, and it warns; a rule that essentially never does may block.
| rule | Debian | GitHub | level |
opens <Name> is a… | 0.02% | 7.8% | block |
| contains a URL | 0.01% | 2.0% | block |
| contains emoji | 0.04% | 16.2% | block |
| superlative | 0.17% | 5.3% | block |
| over 100 characters | 0.19% | 28.7% | block |
| first person | 0.20% | 2.0% | block |
| opens with an article | 0.35% | 26.8% | block |
| over 80 characters | 2.32% | 38.3% | warn |
| repeats its own name | 1.15% | 27.8% | warn |
| two or more commas | 1.01% | 27.0% | warn |
The three warnings are the interesting ones, which is exactly why they must not block. Two or more commas is the sharpest single discriminator found — 27.0% against 1.01% — and it is what a feature list looks like when it is wearing a pitch's clothes. But Debian ships 866 synopses with two commas that are right, so it is a question, not a defect.
Mechanically-enforced rules hold; prose-only ones leak. Homebrew's ten-rule description cop has
zero violations across 8,595 shipped formulae, while the same project's prose rule against
marketing adjectives leaks — fast at 3.0%, modern at 1.2%. Put in the checker whatever you
actually care about.
Two style rules have no right answer, so the target supplies it
Real registries hold opposite positions, and a checker that picks a side is wrong about half its targets:
| axis | who requires it | who forbids it |
| trailing period | Obsidian (90.3% comply) | Homebrew; Debian omits it in 99.1% |
| leading capital | AppStream; Homebrew | Debian lowercases 26.19% deliberately |
Both are off unless asked for: --style trailing-period=required,
--style leading-capital=forbidden.
What the numbers say a good one looks like
Across those 856 repos: median 68 characters, p25 43, p75 111. 80% are noun phrases, 8%
verb-initial. The hard ceiling is 350, and surfaces prints every real limit — Show HN 80 (and the
check is len>, so exactly 80 passes, leaving 71 after Show HN:), npm 255 truncated silently
mid-word, PyPI 512, Homebrew 80, Product Hunt tagline 60, X 280 weighted with any URL costing
23 and non-Latin characters costing double.
Naming the parent is surface-dependent, and this was measured rather than reasoned. The same Obsidian plugins name "Obsidian" in 90% of their GitHub repo descriptions and 9.5% in the plugin registry — the directory supplies context a standalone repo cannot. Raycast shows the same gradient inside one product: extensions say "Raycast" 20.3%, commands 1.9%. So decide it per surface; there is no single right answer to carry between them.
What this cannot tell you, and one number that bounds the whole thing
Nothing here scores quality. Across those same 856 repos, the correlation between violating these rules and stars is +0.056 — none, on a sample restricted to 30k stars and up.
So the defensible claims are narrow: a stranger can tell what this is, the same string appears on every surface, and it fits where it is going. "A better pitch gets more stars" is not among them, and no output of this skill should imply it.
Left to a person: whether the category noun is the right one ("package manager" beats "toolchain" and no script knows that), whether the claim is true, whether it parses for somebody who is not the author, and whether an analogy flatters a competitor — only 2.1% of descriptions name one, and 10 of those 18 are "alternative to X", which is a positioning bet rather than a style choice.
Where the output may go
Not into a community venue as generated text. Hacker News' guidelines say plainly "Don't post
generated text or AI-edited text", and its Show HN tips add "Write your text by hand. Don't use an
LLM to generate any of it (not even a tiny bit, including to edit or spruce it up)."
awesome-readme's admission criteria say the same independently: "The description should be
written by a person. Not AI." dev.to bans AI-assisted articles that promote your own project at
all.
A draft one-liner for your own repo's About box is your text and this is a checker. A Show HN title is not, and no amount of "it only edited it slightly" changes that.
Fixing drift, once drift reports it
Pick the wording that survives the shortest surface, then put that exact string everywhere. The GitHub description is the one people forget, because nothing shows it next to the README — and it is the one a search result renders.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

