From grimoire
Establishes naming conventions for artifact types such as APIs, database tables, files, functions, CLI commands, and event names to ensure consistency and searchability across a project.
How this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:design-naming-conventionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Define a naming convention for a new artifact type so that every name in the namespace
Define a naming convention for a new artifact type so that every name in the namespace is consistent, predictable, and searchable — before contributors add to it at scale.
Adopted by: Google mandates naming conventions across all 6 primary languages via published Style Guides (Java, Python, C++, Go, JavaScript, Shell), enforced via automated linting in every code review. Microsoft's .NET Framework Naming Guidelines (in use since 2002) are adopted across the entire .NET ecosystem of 7M+ developers. AWS enforces resource naming patterns across all 200+ services. Linux kernel has had a formal naming standard since 1991 with zero exceptions permitted in mainline. Impact: Feitelson, Rabinovich, Spektor & Yehudai (2020, ICPC) found that consistent identifier naming is the single strongest predictor of code comprehension speed — consistent names reduced time-to-understand by 19% vs. inconsistent names in the same codebase. Teams with documented naming conventions onboard contributors 2–3× faster because new contributors can predict names before looking them up (Google Engineering Practices, internal study cited in "Software Engineering at Google", 2020). Why best: Ad-hoc naming degrades under scale — early names set unintentional precedents, contributors diverge, grepping fails. Over-specified naming (full descriptive phrases) increases typing burden and exceeds tool character limits. A convention establishes the minimum specificity that makes names both predictable and searchable.
Sources: Google Style Guides, Microsoft .NET Naming Guidelines, AWS API Design Guide, Feitelson et al. (2020) ICPC, "Software Engineering at Google" (Winters, Manshreck, Wright)
State exactly what you're naming and what you're NOT naming:
If multiple artifact types exist (e.g., tables AND columns AND indexes), design a convention for each separately — they have different constraints and usage patterns.
Before designing, extract what already exists:
# Functions in a codebase
grep -r "^def \|^func \|^function " --include="*.py" --include="*.go" --include="*.js" | \
sed 's/.*def //;s/.*func //;s/.*function //' | sort | head -50
# REST endpoints
grep -r "router\.\|app\." --include="*.js" | grep -oP '"[^"]*"' | sort -u
# Database tables
psql -c "\dt" | awk '{print $3}'
Look for: patterns that already exist, conflicts, inconsistencies. Your convention should formalize what's already working and fix what isn't — not ignore existing names.
Select the structural pattern that fits the artifact type:
| Artifact | Common pattern | Example |
|---|---|---|
| Functions / skills | <verb>-<noun> | calculate-tax, review-contract |
| REST resources | /<noun-plural>/<id> | /users/123/orders |
| Database tables | <noun_plural> (snake_case) | user_accounts, payment_events |
| Database columns | <noun> or <adjective_noun> | created_at, is_active |
| Events / messages | <noun>.<past-verb> | order.placed, payment.failed |
| Files | <noun-or-verb>.<ext> (kebab) | auth-middleware.ts, parse-config.go |
| CLI commands | <verb> <noun> | git commit, docker build |
| Feature flags | <team>_<feature>_<state> | payments_new_checkout_enabled |
If none fit, define your own pattern — but it must have: a fixed structure, a clear rule for each segment, and examples of correct and incorrect usage.
If your pattern includes a verb, define the approved verb set explicitly. This prevents
contributors from coining vague verbs (handle-, manage-, do-) that obscure intent.
For each verb in your tier:
State the minimum and maximum specificity required for the subject/noun:
data, info, item, thing) fail this testuser_account_email_address_verification_token_expiry) fail thisRule of thumb: 2–4 words covers 90% of cases. Flag anything shorter (probably too vague) or longer (probably two concepts in one name).
State explicitly which abbreviations are permitted:
api, sql, id, url, uuid, http, dto, ui)usr_acct_verif_tkn_exp — internal shorthands that save 15 chars but cost hours)When do you add a qualifier to avoid collision?
<domain>_ prefix only when names collide across
services. Do NOT add prefixes preemptively."Document all mechanical rules:
snake_case, camelCase, PascalCase, kebab-case, SCREAMING_SNAKEcreate-user) vs. past tense (user-created) — pick oneProduce a decision table + good/bad examples. This is the section contributors bookmark. It must be scannable in 30 seconds:
Pattern: <verb>-<noun>[-<qualifier>]
✅ calculate-tax-rate (verb + specific noun)
✅ review-saas-contract (verb + specific noun + qualifier)
❌ handle-tax (rejected verb)
❌ calculate-stuff (noun too generic)
❌ calculate-the-applicable-tax-rate-for-current-jurisdiction (too long)
A convention not enforced decays within 6 months:
CONTRIBUTING.md or equivalent contributor guide<convention-doc> pattern"If you can't automate, designate a reviewer whose job includes convention compliance.
Designing too late: waiting until 200 names exist creates a migration cost. Design before the third contributor joins.
Over-constraining verbs: a 3-verb tier (create, get, delete) doesn't cover
the real action space — contributors invent workarounds. Start with 8–12 verbs.
No abbreviation policy: "use common sense" produces half the team writing usr and
the other half writing user. Enumerate the allowed list.
Convention without examples: abstract rules without concrete right/wrong examples are ignored. The decision table is not optional.
Retrofitting inconsistently: when fixing existing names to comply, either fix all of them or none — partial fixes create a two-tier system harder to learn than the original inconsistency.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireChoosing meaningful, pronounceable names that reveal intent for functions, variables, classes, and modules.
Enforces precise naming for variables, functions, classes, files, and identifiers. Bans vague names like data/temp/result/info/handle/manager; promotes semantic accuracy and domain-specific terms via specificity ladder.
Name variables, functions, classes, and directories using the vocabulary of the problem domain to improve readability and reduce cognitive translation tax. Useful for new team members or when domain experts use different terms.