Skip to content

Improve README clarity #240

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
santhosh290605 wants to merge 1 commit into from
Closed

Improve README clarity #240

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 1 addition & 128 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

Check failure on line 1 in README.md

View workflow job for this annotation

GitHub Actions / lint

Files should end with a single newline character 

README.md:1:5664 MD047/single-trailing-newline Files should end with a single newline character https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md047.md
Loading