zrosenbauer npm-namer
Finds available npm package names. Bundles a Node script (scripts/npm-namer/dist/check.mjs) that runs four layers of check:
- Syntactic validation — thin wrapper over the official
validate-npm-package-namepackage (uppercase, leading char, length, URL-safe, core-module shadow, etc.) - Availability — parallel HEAD requests to
registry.npmjs.orgfor each candidate - Moniker collision — npm's publish-time rule (lowercase + strip
.-_); catchesestoolkitcolliding withes-toolkit - Near-match (typosquat) warning — Damerau-Levenshtein distance against the top ~15,000 most-downloaded npm packages (TypoGard's published threshold, sourced from
nice-registry/download-counts); catchesextoolkitas suspiciously close toes-toolkiteven though it would publish fine per the moniker rule
The full rule set the script encodes is in references/moniker-rules.md — load that when the user asks why a name fails.
Inputs
$ARGUMENTS — one of:
- Seeds + concept: "i want a tiny logging lib. seeds: tinylog, microlog, jslog" → permute + check
- Concept only: "name a cli that queries bigquery in the terminal" → brainstorm seeds, then permute + check
- Pre-checked list: "are these taken? a, b, c, d" → batch check only, no brainstorming
- Empty → ask what kind of package needs naming
Workflow
1. Classify the request
| Signal in the prompt | Mode |
|---|---|
| User gave explicit seed words or candidates | find (permute the given seeds) |
| User described a concept but listed no names | brainstorm-then-find (you generate seeds, then permute) |
| User listed names asking "which are taken?" | check (batch check only, skip permutation) |
If unclear, ask once with concrete options. Default to brainstorm-then-find when the user describes a package concept.
2. Brainstorm seeds (only in brainstorm-then-find mode)
Generate 10–20 candidate seed words that capture the concept's essence. Mix:
- Direct nouns from the concept ("log", "bigquery", "query")
- Metaphors ("forge", "sage", "smith", "lens")
- Compact forms ("bq", "sql", "log")
- Verbs that describe what the tool does ("scout", "probe", "ping")
Print the seed list so the user can edit it before you run the script. Don't try to be the user's taste — give them range.
3. Run the script
The script lives at skills/npm-namer/scripts/npm-namer/dist/check.mjs in the skills authoring repo and at .agents/skills/npm-namer/scripts/npm-namer/dist/check.mjs in installed skills. Use whichever path resolves in the current project.
# find mode (permute seeds, check candidates)
node skills/npm-namer/scripts/npm-namer/dist/check.mjs <seed1> <seed2> ... --limit 50
# check mode (no permutation, just verdicts on given names)
node skills/npm-namer/scripts/npm-namer/dist/check.mjs --check <name1> <name2> ...
# from stdin or file
node skills/npm-namer/scripts/npm-namer/dist/check.mjs --stdin
node skills/npm-namer/scripts/npm-namer/dist/check.mjs --file ./candidates.txt
Pass --limit for how many candidates to check (default 50; raise for thorough searches). Use --scope @user to generate scoped variants. Use --json if you need machine-parseable output for downstream steps.
--exhaustive runs a slower 2-insertion moniker variant pass — turn it on when the user is about to publish and wants belt-and-suspenders coverage. --no-near-match disables the typosquat similarity warning if the user wants only the official npm rule. --near-distance N tunes the edit-distance threshold (default 2; 1 catches only the tightest typosquats, 3 widens to looser similarities).
4. Interpret the output
The script's text output has six status verdicts plus an optional near-match annotation:
| Verdict | Meaning |
|---|---|
✓ available |
Free on registry AND no moniker collision found. May still carry a near: warning. |
⚠ moniker |
Free literally but normalizes to an existing package — publish will be rejected. The line includes collides with: ... |
⚠ unverified |
Free literally but moniker check incomplete — some variant probes failed (rate limit / network). Do NOT treat as safe; rerun or use npm publish --dry-run. |
✗ taken |
A package with that exact name is already published |
✗ invalid |
Fails syntactic rules (e.g., uppercase, leading dot, length > 214) |
? unknown |
Registry returned non-200/404 for the literal name (rate limit, network) — surface to user |
Near-match annotation appears alongside ✓ available when the candidate is within 2 edits of a popular npm package. Format: near: <pkg> (d=<distance>). This is publishable but typosquat-shaped — bring it to the user's attention.
Output groups results into three buckets at the bottom:
- Available + moniker-clear + no typosquat shape — safe picks.
- Available but typosquat-shaped — publishable but visually confusable with popular packages. Let the user decide.
- Moniker check incomplete — candidates with
unverifiedstatus. Rerun or usenpm publish --dry-runbefore publishing.
Known limitation: 3+ morpheme moniker checks
The moniker check enumerates 1- and 2-separator variants. 3+ morpheme splits are not covered even with --exhaustive — e.g., a candidate eslintpluginreacthooks would not surface eslint-plugin-react-hooks as a collision. The blog-rule normalization (lowercase + strip [._-]) catches this server-side, but client-side variant enumeration is combinatorially bounded. For multi-morpheme names (≥3 segments), recommend npm publish --dry-run against the live registry for authoritative pre-flight.
5. Present a shortlist
Don't just dump the script output. Pull the top 3–5 available candidates and present them ranked by:
- Length (shorter wins)
- Hyphenation (readable beats concatenated)
- Containing a seed word (relevance to concept)
Quote the moniker collisions explicitly if any of the user's own suggestions were blocked — they'll want to know which existing package collides so they can decide if they care.
Examples
node skills/npm-namer/scripts/npm-namer/dist/check.mjs tinylog microlog jslog picolog --limit 50
Output (abbreviated):
seeds: tinylog, microlog, jslog, picolog
considered: 287 candidates
checked: 50 candidates
moniker: standard collision check
────────────────────────────────────────────────────────────────
✗ taken tinylog
✗ taken microlog
✗ taken jslog
⚠ moniker pico-log collides with: picolog
✓ available tinylog-forge
✓ available pico-log-kit
✓ available lean-microlog
...
Shortlist for the user:
pico-log-kit— tiny, descriptive, moniker-clearlean-microlog— riffs on their existing tastetinylog-forge— generative suffix; readable
All four of your originals are taken (picolog collides under the moniker rule too).
node skills/npm-namer/scripts/npm-namer/dist/check.mjs --check querysmith bqterm sqlsage sqlforge
Read the verdicts, present them inline. No permutation. If all four are taken, then offer to brainstorm alternates — but don't preempt.
Script reference
The shipped CLI is a single bundled file (check.mjs) produced by skill-scripts/npm-namer/. The source uses installed npm packages (validate-npm-package-name, damerau-levenshtein) — tsdown bundles them into a self-contained file the consumer can run with zero install. Never edit the bundled check.mjs — edit skill-scripts/npm-namer/src/ and run pnpm --filter @zrosenbauer/skill-scripts-npm-namer build.
scripts/npm-namer/dist/check.mjs— bundled CLI (auto-generated). Run with--help.scripts/npm-namer/popular-names.json— top ~15,000 unscoped npm packages by monthly downloads, sourced fromnice-registry/download-counts. Committed build artifact.scripts/npm-namer/refresh-popular-names.mjs— regeneratepopular-names.jsonfrom a freshdownload-countssnapshot.
Source modules (at skill-scripts/npm-namer/src/):
check.mjs— CLI entry (the build's input)validate.mjs— thin wrapper aroundvalidate-npm-package-namemoniker.mjs— moniker normalization + variant enumerationnear-match.mjs— Damerau-Levenshtein typosquat similarity (viadamerau-levenshtein)permute.mjs— deterministic seed → candidate permutation engineregistry.mjs— parallel HEAD requests toregistry.npmjs.org
Build + test from source:
pnpm --filter @zrosenbauer/skill-scripts-npm-namer build # tsdown → skill-scripts/npm-namer/dist/check.mjs
pnpm --filter @zrosenbauer/skill-scripts-npm-namer test # node --test against unbundled source
pnpm skill-toolkit sync # vendor → skills/npm-namer/scripts/npm-namer/
References
references/moniker-rules.md— authoritative rule set: syntactic rules with verbatim error strings, the moniker collision algorithm with source citations, scoped-package behavior, the near-match (typosquat) layer this skill adds on top, edge cases (security-holder packages, unpublish burn, legacy mixed-case names), and a survey of alternative tooling.