Naming

naming

node .agents/skills/naming/scripts/config.mjs

Rules

1. One word per thing, and the word comes from

   CONTEXT.md

   . Look there first, then in existing types, DB tables and API routes. The repo's word beats the request's word.

   Good	Bad	Why
   testimonial	customerQuote	the request said "customer quotes", the repo says testimonial
   Testimonial type, testimonials table, /api/testimonials	Testimonial type, reviews table	one word per thing, everywhere
   order	purchase beside order	two words for one thing splits the search

2. No word yet? Run term-check, show the result to the user, get sign-off, then add the word to

   CONTEXT.md

   through domain-modeling, which owns that file.

   Good	Bad	Why
   carryOver , term-checked, in CONTEXT.md	carryOver , invented in the PR	a new word needs the user's sign-off
   caseStudy recorded with plural caseStudies	caseStudy with no entry	the next agent picks a different word
   grid added to the role list	Grid used, list unchanged	a role outside the closed list is a new word

3. Name by role, not by type. No

   I

   or

   T

   prefix, no Hungarian, no noise word (see

   noiseWords

   in naming.json).

   Good	Bad	Why
   User	IUser	no I prefix
   count	nCount	no Hungarian
   accounts	accountList , accountData	no noise word, the plural already says many

4. Full words only, no single-letter name, no magic number. The banned short words are

   shortWords

   in naming.json.

   Good	Bad	Why
   options	opts	full word
   error	e , err	no single letter, no abbreviation
   const MAX_RETRIES = 3	a bare 3	a number needs a name

5. Say nothing the call site already says.

   Good	Bad	Why
   user.name	user.userName	the object says user
   testimonials.add(item)	testimonials.addTestimonial(item)	the collection says testimonial
   field name in table testimonials	field testimonial_name	the table says testimonial

6. An action starts with a verb from

   prefixes

   in naming.json, one verb per meaning. A pure derived value may be a noun.

   Good	Bad	Why
   fetchTestimonials	loadTestimonials beside it	one verb per meaning, fetch is over the network
   listUsers	getAllUsers	list means many
   branchSha	getBranchSha	a pure derived value may be a noun

   A prefix promises its meaning:

   get

   only reads,

   set

   returns nothing,

   is

   returns a boolean,

   find

   may return nothing while

   get

   may not. A name with

   and

   in it (

   saveAndNotify

   ) is two functions.
7. Stored boolean state is a bare adjective; a check is

   is

   ,

   has

   ,

   can

   or

   should

   ; never

   notX

   .

   Good	Bad	Why
   archived	isArchived	stored state is a bare adjective
   isEmpty , canRetry	empty() , retryAllowed	a check carries the prefix
   enabled	notDisabled	positive names only

8. Entity singular, collection plural. Record an irregular plural in

   CONTEXT.md

   next to the word.

   Good	Bad	Why
   type Testimonial , file testimonial.ts	type Testimonials	one entity is singular
   table, path, folder testimonials	table testimonial	a collection is plural
   case_studies , plural recorded in CONTEXT.md	case_studys	an irregular plural is written down once

9. No

   enum

   . Use a string-literal union or an

   as const

   object. The discriminant key is

   discriminant

   in naming.json (

   kind

   ). Own values are kebab-case; values mirrored from an external API stay verbatim.

   Good	Bad	Why
   type Status = 'open' | 'in-progress'	enum Status { Open }	no enum
   { kind: 'pull-request' }	{ type: 'pull-request' }	the discriminant key is kind
   'MERGED' from the GitHub API	'merged'	a mirrored value stays verbatim

10. Build every name from

    parts

    in naming.json, big to small:

    project · area · entity · role · action · attribute · consumer

    . Take the parts you need, keep their order. Each

    artifacts

    entry lists parts, case and examples.

    role

    is a closed list per repo (

    artifacts.component.roles

    ,

    artifacts.env.roles

    ). Env vars follow

    artifacts.env.shape

    . Payload CMS: collection slug = API path = table; the slug is kebab-case and plural (

    case-studies

    ), the table replaces the hyphen with an underscore (

    case_studies

    ).

    Good	Bad	Why
    COLIN_SYNC_KEY_FOR_TWENTY	TWENTY_API_KEY	issuer first, then what the key is for, then who holds it
    TestimonialGrid	GridTestimonial	entity first, then role
    testimonial.added	addTestimonial	an event is a fact in the past, not a command

11. Casing follows the language guide and the repo's linter. Files and folders are lowercase kebab-case. An existing repo convention wins over this line: set it in

    artifacts.file.case

    and

    artifacts.folder.case

    , one case or a list (

    ["kebab", "PascalCase", "camelCase"]

    for React components and hooks).

    Good	Bad	Why
    render-pr-body.mjs	renderPrBody.mjs	files are kebab-case
    src/components/case-studies/	src/components/case_studies/	folders are kebab-case
    loadUser in a repo that uses load everywhere	fetchUser beside it	the existing convention wins

12. Meaning changed? Rename everywhere in the same change, rule 204 in writing-rules.

    Good	Bad	Why
    draft renamed to proposal in code, docs and DB in one PR	code renamed, docs still say draft	two words for one thing
    retryCount after the value stopped being a limit	maxRetries kept	the name lies
    rename plus a CONTEXT.md update	rename only	the glossary is the source

Per-project overrides

.skilly/naming.json

docs/agents/naming.json

.skilly/naming.json

.skilly/naming.json

• Objects merge by key.

  null

  drops a key.
• Arrays append and dedupe.

  "-Data"

  drops the default

  Data

  .
• Scalars override.

{
  "prefixes": { "sync": { "meaning": "mirror to a remote system", "not": ["push", "mirror"] } },
  "noiseWords": ["-Data"],
  "allow": ["^ctx_"]
}

allow

References

• references/naming.json: prefixes, parts, artifacts, short words, noise words, synonyms, discriminant, allow
• references/lint.md: what the CI gate checks, what you judge, per-repo exceptions
• references/biome.json: opt-in Biome block for consumers
• scripts/config.mjs: prints the merged config