audit-registry-listing · diff
git:20260917.494dc23 to git:20260923.cf348bd
2 added, 1 removed. Audit A to A.
---
name: audit-registry-listing
description: >
Read-only audit of where a repo is discovered: README first screen, npm /
PyPI metadata and tarball, GitHub description, topics, social preview,
plugin manifests, install one-liner. Use when "audit our npm listing",
"README as landing page", "GitHub topics", "why nobody finds the package".
Fix → enhance-readme.
license: MIT
+ effort: high
---
# audit-registry-listing — The registry is the landing page
**Degree of freedom: MIXED.** What the first screen should say
`[HIGH freedom]`; the metadata checklist and the tarball check
`[LOW freedom — run exactly]`.
Read-only. For a package, plugin, skill pack, or CLI, discovery happens in a
registry and the README's first ten lines are the hero. This skill checks
every surface a stranger sees before the repo, reports gaps with evidence,
and hands fixes to the owning skills.
## This skill vs neighbors
| Skill | Owns |
|---|---|
| **audit-registry-listing** (this) | Findings on README hero, registry metadata, GitHub surface, manifests, install path |
| `enhance-readme` | Hero image, tour grid, screenshots — the fix |
| `docs-writer` | README prose, quickstart wording |
| `deploy-npm` | The publish itself; `files`/`publishConfig` changes ship through it |
| `plan-aso` | App Store / Play listings |
| `enhance-web-seo` | The website, not the registry |
| `plan-dependency-provenance` | Whether *dependencies* are real — not this package's listing |
Do **not** fire for "make the README prettier" → `enhance-readme`.
## How to reason
1. **Surface** — which registry or page does a stranger hit first for this repo?
2. **Ten lines** — can they say what it is, for whom, and how to install, before scrolling?
3. **Metadata** — does the registry card (name, description, keywords, homepage, repo, license) say the same thing?
4. **Tarball** — does the published artifact contain what the README promises and nothing it should not?
5. **Path** — install to first success in under a minute, on a clean machine?
## Worked example
> **Surface:** npm page + skills.sh card + GitHub repo.
> **Ten lines:** README opens with a logo and a count ("145 skills · 57 commands"); the outcome appears in paragraph 3.
> **Metadata:** npm description repeats the count; GitHub description empty; 4 topics; no social preview; `homepage` points at skills.sh (good).
> **Tarball:** `npm pack --dry-run` shows `docs/screenshots/` (12 MB) shipping; `llms.txt` present.
> **Path:** `npx @kensaurus/cursor-kenji --all` works; first-run message tells the user to restart Cursor — good.
> **Findings:** hero leads with counts (major → `enhance-readme`/`docs-writer`); GitHub description + preview missing (minor → repo settings); screenshots bloat the tarball (minor → `deploy-npm` `files`).
## Self-critique before reporting
- **Evidence** — every finding quotes the line, field, or `npm pack` output
- - **Stranger test** — the ten-line verdict was made without repo knowledge (fresh model or fresh reader)
+ - **Stranger test** — the ten-line verdict comes from a fresh-context subagent given only the README's first ten lines and the registry card, nothing else from the repo; this is the one place delegation pays here, because once you have read the repo your own read is no longer a stranger's
- **No fixes applied** — findings and owners only
- **Right owner** — visuals → `enhance-readme`; prose → `docs-writer`; `files` → `deploy-npm`; store → `plan-aso`
---
## Checklist [LOW freedom — run exactly]
### A · README first screen
- Line 1–10: name, one outcome sentence (not a count), who it is for, install one-liner, one screenshot or terminal GIF.
- Badges: version, license, one live proof (installs/downloads); no broken or stale badges.
- Quickstart to first success ≤ 5 steps; a "what it is not" line.
### B · Registry metadata (npm / PyPI / crates / gems)
- `name`, `description` (outcome-first, ≤ 140 chars), `keywords` (the queries people type), `homepage`, `repository`, `bugs`, `license`, `engines`.
- README rendered on the registry equals the repo README (or a deliberate short version).
- `npm pack --dry-run` / `python -m build` listing: everything promised present; no `.env*`, keys, screenshots, tests, or 10 MB+ assets unless intended; `files` whitelist present.
- `bin` names match the README; `npx <pkg>` runs without a global install.
- Provenance / trusted publishing badge if available.
### C · GitHub surface
- Repo description (outcome, ≤ 120 chars), website URL, ≥ 5 topics that match the keywords, social preview image set (1280×640), releases with notes, pinned issue or discussion for feedback, `SECURITY.md`, license detected.
### D · Ecosystem manifests
- skills.sh / Cursor / Claude / Codex / Gemini plugin manifests: version in sync with the package, description in sync, install command correct on each surface, listing status honest (submitted ≠ listed).
- MCP registry only if the repo ships a runnable server.
### E · Install path
- On a clean profile (temp HOME): install one-liner → first successful action; note every prompt, restart, or missing-key stop; time it.
## Report template
```markdown
# Registry Listing Audit — <package>
## Surfaces checked
| Surface | URL | Fetched |
## Ten-line verdict (stranger read)
What it is: … · For whom: … · How to install: … · Missing: …
## Findings
| # | Surface | Gap | Evidence | Sev | Owner skill |
## Tarball
`npm pack --dry-run` — N files, X MB; unexpected: …
## Install path
Steps … · Time … · Stops …
## Handoff
`enhance-readme` (hero/screenshots) · `docs-writer` (prose) · `deploy-npm` (`files`, metadata) · repo settings (description, topics, preview)
```
## Guardrails
- **Read-only.** No README, manifest, or repo-settings edits here.
- **No count-led heroes.** Recommend the outcome sentence; counts go in a badge.
- **Honest listing status.** "Submitted" and "listed" are different words.
## Chains with
- **`plan-gtm`** → for repo-as-product, this is Phase 1 evidence.
- **`enhance-readme`** / **`docs-writer`** → apply the findings.
- **`deploy-npm`** → ship metadata and `files` fixes.
- **`docs-launch-kit`** → announce the refreshed listing.