From c68fefd30d267762b13b534a768a275cfea5dc25 Mon Sep 17 00:00:00 2001 From: santhosh290605 Date: Sun, 15 Mar 2026 20:52:50 +0530 Subject: [PATCH] Improve README clarity --- README.md | 129 +----------------------------------------------------- 1 file changed, 1 insertion(+), 128 deletions(-) diff --git a/README.md b/README.md index 6ea7c1c..44a6c1c 100644 --- a/README.md +++ b/README.md @@ -1,128 +1 @@ -# naming - -A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill for naming products, SaaS tools, brands, and projects. - -Metaphor-driven naming that produces memorable, meaningful names — and avoids AI slop. - -## What this does - -When invoked, this skill guides Claude through a structured naming process: - -1. **Naming brief** — establish what the product does, who it's for, what it should feel like -2. **Metaphor exploration** — map conceptual territories before brainstorming names -3. **Candidate generation** — produce names grounded in metaphor, not thesaurus surfing -4. **Filtering** — kill AI slop and anti-patterns -5. **Evaluation** — score and compare finalists with a weighted rubric -6. **Availability checking** — verify domains, handles, and package names -7. **Decision** — present top candidates with origin stories and trade-offs - -## Install - -### As a project skill (this project only) - -Clone or copy the repo contents into your project's `.claude/skills/naming/` directory: - -```bash -# From your project root -mkdir -p .claude/skills -git clone https://github.com/glacierphonk/naming.git .claude/skills/naming -``` - -### As a personal skill (all projects) - -```bash -mkdir -p ~/.claude/skills -git clone https://github.com/glacierphonk/naming.git ~/.claude/skills/naming -``` - -## Usage - -In Claude Code: - -```text -/naming -``` - -Then describe what you need a name for. Claude will walk you through the full process. - -You can also reference the skill naturally in conversation — describe your naming challenge and Claude will pull in the relevant reference files. - -### Quick start - -You don't need to read any of the reference files before using the skill. Just: - -1. Type `/naming` -2. Describe what you're building in one sentence -3. Claude handles the rest — it loads the right references at each step - -The 7-step process and 14 reference files are the depth layer. For a quick naming session, Claude compresses the process automatically. The reference files exist so you can dive deeper when needed. - -## Files - -| File | Purpose | -| ------ | ------- | -| `SKILL.md` | Entry point — process overview and navigation | -| `principles.md` | Core naming principles (metaphor, real words, compounds, length) | -| `phonosemantics.md` | Sound-meaning connections — how sounds convey attributes | -| `anti-patterns.md` | AI name slop, fatal flaws, red flags checklist | -| `metaphor-mapping.md` | How to explore metaphor territories + starter maps | -| `cultural-references.md` | When mythology/literature/science references work vs. fail | -| `brand-architecture.md` | Naming within brand families and product lines | -| `availability.md` | Platform checking workflow and domain landscape | -| `case-studies.md` | Real product name origins and analysis | -| `evaluation.md` | Scoring rubric, comparison framework, decision checklist | -| `language-rules.md` | Working with foreign words — pronunciation, diacritics, transliteration, exoticism trap | -| `scripts/check-availability.sh` | Bundled availability checker for domains, npm, GitHub, PyPI, Telegram, etc. | -| `languages/INDEX.md` | Language-specific naming guides — see [index](languages/INDEX.md) for available languages (Polish, Portuguese, and more) | -| `industries/INDEX.md` | Industry-specific naming guides — see [index](industries/INDEX.md) for available industries | - -New language and industry files welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for templates and required sections. - -## Philosophy - -**Names are compressed stories, not labels.** The best names plant a concrete image that unfolds into understanding — what the product does, what it feels like, where it comes from. - -This skill is opinionated: - -- **Metaphor over thesaurus.** Don't search for synonyms of your product's category. Explore what else in the world works like your product. -- **Real words over invented words.** Real-word brand names have ~68.8% recall vs ~38.1% for invented names. The brain follows the path of least resistance. -- **Story over sound.** A name with a great origin story and average sound will outperform a name with perfect phonetics and no story. -- **Kill AI slop.** Suffixes like -ly, -ify, -able, meaningless portmanteaus, and thesaurus extraction produce polished-but-interchangeable names. This skill actively filters them out. - -## How the skill uses context - -- **Always loaded:** Skill name and description (~2% of context budget) -- **Loaded on invoke:** SKILL.md (~180 lines, the process overview) -- **Loaded on demand:** Reference files load only when Claude reaches the relevant step. A simple naming task might only load 2-3 files; a thorough session loads 5-6 -- **Never auto-loaded:** Language files, case-studies.md — only when explicitly relevant - -Contributors: keep reference files focused. A 500-line file is fine; a 2,000-line file wastes context on content that may not be relevant. - -## Development - -### Linting - -PRs are checked by [markdownlint](https://github.com/DavidAnson/markdownlint) and [lychee](https://github.com/lycheeverse/lychee) (link checker) via GitHub Actions. - -Common lint rules to watch: -- **MD040** — fenced code blocks need a language tag (use `text` for plain text, `bash` for shell, `markdown` for markdown examples) -- **MD001** — heading levels must increment by one (`##` → `###`, not `##` → `####`) -- **MD037** — no spaces inside emphasis markers. Use `` `___` `` (code backticks) for placeholders, not `___` (which looks like emphasis) - -Run locally before pushing: - -```bash -npx markdownlint-cli2 '**/*.md' -``` - -### Branch protection - -`main` is protected — all changes go through pull requests. Direct pushes are blocked. - -## Contributing - -PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions, file structure, and how to add language files or case studies. - -## License - -[MIT](LICENSE) +# namingA [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill designed to help you name products, SaaS tools, brands, and projects.It uses metaphor-driven naming to create memorable, meaningful names — while avoiding common AI-generated fluff.## What this doesWhen you run this skill, it guides Claude through a clear, step-by-step naming process:1. **Naming brief** — Define what the product does, who it is for, and the desired feel2. **Metaphor exploration** — Explore related conceptual areas before brainstorming3. **Candidate generation** — Generate name ideas based on metaphors, not just synonym searching4. **Filtering** — Remove generic or weak AI-generated names5. **Evaluation** — Score and compare top candidates using a weighted rubric6. **Availability checking** — Check domain names, social handles, and package names7. **Decision** — Present the best options with their stories and trade-offs## Install### For this project only (project skill)Copy or clone the repo into your project's `.claude/skills/naming/` directory:```bash# Run from your project's root directorymkdir -p .claude/skillsgit clone https://github.com/glacierphonk/naming.git .claude/skills/naming```### For all your projects (personal skill)```bashmkdir -p ~/.claude/skillsgit clone https://github.com/glacierphonk/naming.git ~/.claude/skills/naming```## UsageIn Claude Code, start by typing:```text/naming```Then describe what you need named. Claude will guide you through the entire process.You can also mention the skill naturally during a conversation — just describe your naming challenge, and Claude will reference the relevant files.### Quick startYou don't need to read any reference files beforehand. Just:1. Type `/naming`2. Explain what you're building in one sentence3. Claude takes care of the rest, loading relevant references as neededThe 7-step process and 14 reference files provide depth for thorough naming. For quick sessions, Claude shortens the process automatically.## Files| File | Purpose || ------ | ------- || `SKILL.md` | Main entry point — overview of the process and navigation || `principles.md` | Core naming principles (metaphors, real words, compounds, length) || `phonosemantics.md` | How sounds convey meaning and attributes || `anti-patterns.md` | Checklist of AI-generated name pitfalls and red flags || `metaphor-mapping.md` | How to explore metaphor spaces and sample maps || `cultural-references.md` | When references from mythology, literature, or science help or hurt || `brand-architecture.md` | Naming strategy within brand families and product lines || `availability.md` | How to check availability on domains and platforms || `case-studies.md` | Real-world examples of product names and their analysis || `evaluation.md` | Scoring rubric and decision checklist || `language-rules.md` | Working with foreign words—pronunciation, diacritics, transliteration, and common traps || `scripts/check-availability.sh` | Script to check availability on domains, npm, GitHub, PyPI, Telegram, and more || `languages/INDEX.md` | Language-specific naming guides — see [index](languages/INDEX.md) for available languages (e.g., Polish, Portuguese) || `industries/INDEX.md` | Industry-specific naming guides — see [index](industries/INDEX.md) for covered industries |We welcome new language and industry files! See [CONTRIBUTING.md](CONTRIBUTING.md) for templates and required sections.## Philosophy**Names are compressed stories, not just labels.** The best names evoke a vivid image that reveals what the product does, how it feels, and its origin.This skill follows these core opinions:- **Metaphor over thesaurus.** Instead of searching for synonyms, explore what else in the world works like your product.- **Real words over invented ones.** Real-word brand names have about 68.8% recall compared to 38.1% for made-up names. The brain favors familiarity.- **Story over sound.** A good origin story outweighs perfect phonetics in making a name memorable.- **Kill AI slop.** Remove common AI-generated suffixes (-ly, -ify, -able), meaningless blends, and thesaurus fishing to avoid generic names.## How the skill uses context- **Always loaded:** Skill name and description (~2% of context budget)- **Loaded on invoke:** `SKILL.md` (~180 lines, process overview)- **Loaded on demand:** Reference files load only at relevant steps. Simple tasks may load 2-3 files; thorough sessions 5-6.- **Never auto-loaded:** Language files and `case-studies.md` load only when explicitly needed.Contributors: keep reference files concise. Around 500 lines is fine. Files with 2,000+ lines may waste context on less relevant content.## Development### LintingPull requests are checked automatically with [markdownlint](https://github.com/DavidAnson/markdownlint) and [lychee](https://github.com/lycheeverse/lychee) (link checker) using GitHub Actions.Common lint issues to watch for:- **MD040** — fenced code blocks should specify language (use `text` for plain text, `bash` for shell commands, `markdown` for markdown)- **MD001** — heading levels must increase stepwise (`##` then `###`, not skipping levels)- **MD037** — no spaces inside emphasis markers. Use code backticks `` `___` `` for placeholders instead of underscores alone.Run these checks locally before pushing changes:```bashnpx markdownlint-cli2 '**/*.md'```### Branch protectionThe `main` branch is protected. All changes must go through pull requests; direct pushes are disabled.## ContributingPull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on file structure, naming conventions, adding language files, or case studies.## License[MIT](LICENSE) \ No newline at end of file