naming-is-hard

Files (34)

• .gitignore
• .npmrc
• .vally.yaml
• LICENSE
• README.md
• SKILL.md
• README.md · evals/
• eval.yaml · evals/naming-is-hard/
• package-lock.json
• package.json
• availability-channels.md · references/
• naming-strategies.md · references/
• availability.mjs · scripts/
• famous-marks.json · scripts/
• features.mjs · scripts/
• marks.mjs · scripts/
• model.mjs · scripts/
• naming.mjs · scripts/
• net.mjs · scripts/
• similarity.mjs · scripts/
• smoke.mjs · scripts/
• store.mjs · scripts/
• verdict.mjs · scripts/
• availability.test.mjs · test/
• cli.test.mjs · test/
• features.test.mjs · test/
• helpers.mjs · test/
• marks.test.mjs · test/
• model.test.mjs · test/
• net.test.mjs · test/
• similarity.test.mjs · test/
• store.test.mjs · test/
• verdict.test.mjs · test/
• thumbnail.png

SKILL.md (first lines)

# naming-is-hard

## When to use it

Reach for this whenever a name needs to be chosen and checked: a new project,
product, startup, open-source library, npm/PyPI package, GitHub org or repo, app,
or feature. It is equally good at "brainstorm names for X" and "is "Foo" already
taken everywhere?".

Do not use it to rename variables or functions in code (that is ordinary editing),
or for SEO keyword research.

## On invocation

When the user invokes this skill (e.g. `/naming-is-hard`), **start the naming
flow immediately**. Do not ask "What can I help you with?" or wait passively.

- If the user provided context alongside the invocation (e.g. "name my CLI tool
  that does X"), proceed directly to Act 1 (the Profile) using that context.
- If the user invoked the skill bare with no context, look at the current working
  directory for a README, package.json, or other project files. If you find a
  project, ask one focused question: "I see you're working on [project]. Would you
  like to name this, or something else?" Then proceed to Act 1.
- If there's no project context at all, ask a single question to get started:
  "What are we naming? Tell me what it is and I'll kick off the process."

## Division of labor

You (the agent) do the creative work. The engine does the deterministic,
security-sensitive, and stateful work. Stay on your side of this line.

| You (this SKILL.md) | The engine (`scripts/naming.mjs`) |
|---|---|
| Write the Naming Brief from the context | Extract feature vectors from names |
| Generate creative candidate names + a one-line pitch each | Learn taste from swipes (score / rank / pick next) |
| Present swipe cards via `ask_user` | Explain the learned "type" in plain language |
| Decide when to refill the deck and generate more | Check availability (SSRF-safe, mocked in tests) |
| Run a live `web_search` per finalist for trademarks/businesses | Block obvious offline collisions before cards; compute finalist verdict tiers |
| Narrate the matches and next actions | Persist all state across swipe turns |

**Never** hand-roll availability checks with raw `curl`, and never invent a swipe
score yourself. Call the engine. It is tested and safe.

## The engine CLI

The engine lives in `scripts/naming.mjs`. It needs no install and no network for
anything except `check`. Every command takes `--dir <state-dir>`, a working folder
where the run's state is persisted (use the session workspace, for example
`~/.copilot/session-state/<id>/files/naming-<slug>`). Node 18+.

| Command | What it does |
|---|---|
| `init --dir D [--brief-json '{...}']` | Create (or open) state; optionally set the brief |
| `brief --dir D --json '{...}'` | Set/replace the Naming Brief |
| `add --dir D --json '[{"name":..,"strategy":..,"tags":[..]}]'` | Add candidates (features extracted, ids assigned). Reports offline collisions in `blocked`; those names never enter the deck. Also reads the JSON array from stdin. |
| `next --dir D [--count N]` | Return the next card(s) to show, best first |
| `swipe --dir D --id ID --label like\|pass\|superlike\|skip` | Record a swipe and update the model |
| `rank --dir D [--limit N]` | Candidates ranked by learned fit |
| `profile --dir D` | The learned "type" in plain language |
| `suggest --dir D --name NAME [--count N]` | Morphological variants of a liked name |
| `check --dir D [--names a,b] [--github-token T]` | Availability scorecards (defaults to liked names) |
| `screen --dir D --names a,b,c [--preset P]` | Availability-FIRST: bucket names into clear / contested / blocked by key channels |
| `variants --name NAME` | Decorated handle/org variants (get<X>/<X>hq/<X>dev), screened for GitHub/npm/.dev |
| `similar --name NAME --against a,b,c` | Confusability report against a corpus you supply (from your live search) |
| `duel --dir D --winner ID --loser ID` | Decision mode: record a head-to-head result so the winner's traits outrank the loser's |
| `report --dir D [--names a,b] [--preset P] [--as-json]` | Ranked matches with verdict tiers (human text by default) |
| `state --dir D` | Dump the full state as JSON |
| `reset --dir D` | Clear the state |

All commands print JSON (so you can parse the result) except `report`, which prints
a human-readable card by default and JSON with `--as-json`.

## Act 1: the Profile (Naming Brief)

Never brainstorm from nothing. First understand the thing being named.

**Sources**, in order of richness:
- A **repo or directory path**: read the `README`, `package.json`/manifests, and a
  couple of entry files to infer what it does.
- A **URL** (a PRD, a landing page, a GitHub repo): fetch it with `web_fetch` and
  synthesise.
- **Free text**: use it directly.

Then fill the brief. Keep it tight:

```json
{
  "name": "working title or null",
  "what": "one sentence: what it is and does",
  "willBe": "where it is heading (the ambition)",
  "audience": "who it is for",
  "tone": ["playful", "trustworthy", "technical", ...],
  "keywords": ["concepts", "metaphors", "differentiators"],
  "constraints": [".com-able", "one word", "pronounceable", "<= 8 letters", ...]
}
```

If the context is thin, ask **at most two or three** quick `ask_user` questions to
fill the biggest gaps (usually audience and tone). Do not interrogate. Store it
with `init --brief-json` or `brief --json`.

**Ask what channel matters most** (one quick question). Use `ask_user` with these
options and let their answer pick the verdict `--preset` passed to `report`/`screen`:

| User says | Preset | Key channels (in priority order) |
|---|---|---|
| "npm / CLI / package name" | `cli-first` (default) | npm > `.dev` > GitHub org |
| "`.dev` domain (developer landing page)" | `domain-first` | `.dev` > npm > GitHub org |
| "`.com` domain (website / product)" | `website-first` | `.com` > `.dev` > npm |
| "Brand (domain + social)" | `brand-first` | `.com` > X handle > `.dev` |
| "Social handles" | `social-first` | X > `.dev` > npm |
| "No strong preference" | `balanced` | `.dev` > GitHub org > npm |

**Do not assume a default.** The user's answer fundamentally changes which names are
"Perfect Match" vs "It's Complicated." If they say `.com`, then `.com` availability is
the gating signal — do not dismiss it as "always parked." If they say npm/CLI, then
`.com` is background noise. Respect their stated priority throughout the entire flow.

Also ask whether GitHub org availability matters to them (yes/no). If they say no, do

From jongio/skills, MIT.

More from jongio/skills