agentleFS
Sign inStart free
Autocss-comAutocss-com/ai/.agents/skills/naming/SKILL.md

naming

Skill1 starsChanged 2 months agoMITView on GitHub

Naming rules for files, custom element tags, skills, functions, and CSS custom properties. Names describe the concern, not the implementation, so they survive refactors. Use whenever creating any new named thing or renaming an existing one.

16 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 3 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 12 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the implementation changes from oklch to OkLab, the name themes still describes the concern.

    line 16
  2. Distinctive:

    Never names by implementation detail

    line 119
  3. Very specific:

    Never names by adjective stack (modern-, semantic-, accessible-)

    line 120
  4. Very specific:

    Never embeds a value in a name (--color-blue is bad.

    line 121
  5. Very specific:

    Never uses ambiguous names (utils.js, helper(), data)

    line 122
  6. Distinctive:

    Never relies on symlinks for cross-file references

    line 123
  7. Distinctive:

    No version-sensitive web-platform features are referenced here — everything used is Baseline Widely available.

    line 129

“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Naming

Names describe the concern, not the current implementation. A name should survive any internal change to how the thing works.

Good: layout, transitions, state-machines, themes Bad: holy-grail-layout, oklch-themes, radio-checkbox-state-machines

If the implementation changes from oklch to OkLab, the name themes still describes the concern. The name oklch-themes would lie.

Files

Active vs. inactive

  • Active files have no trailing underscore: layout.css, themes.css, app.js.
  • Inactive files (preserved for reference but not loaded by the runtime) have one or more trailing underscores: typography_.css, typography__.css, fonts_.css. Multiple underscores indicate older inactive versions.

The trailing-underscore convention is a build-tool-free way to mark a file as not part of the active runtime while keeping it visible in the directory.

File-name describes concern

ConcernFile
Reset rulesreset.css
Layoutlayout.css
Typographytypography.css
Themesthemes.css
API transportapi.js
oninput lifecycleoninput.js
Storagestorage.js

Not:

BadWhy
holy-grail.cssImplementation, not concern
dark-mode.cssHalf the concern (themes covers light + dark)
fetch-utils.jsImplementation; api.js is the concern

Custom element tags

Custom elements must contain a hyphen (HTML spec). Tag names describe the role:

  • app-container — the layout root
  • app-logo — the brand mark slot
  • app-user — the user-info slot
  • app-legal — the legal-text slot
  • app-version — the version-display slot
  • app-banner — optional notification slot

For data-rendered elements, see the data-flow skill — toTagName(key) produces the tag from a JSON key.

toTagName, not toKebab

The function is named for what it does (produces a valid HTML tag name), not for the case style it happens to use. If the spec ever permitted other separators, the function name still describes the concern.

Skills

Skills follow the same rule. Skill names describe the concern:

  • html (concern: structural markup), not semantic-html (concerns and adjectives stack)
  • css (concern: UI runtime), not modern-css
  • state-machines (concern: how interactivity is encoded), not checkbox-radio-pattern

Standard requires lowercase letters, numbers, and hyphens only. No underscores in skill names. The skill directory name must match the name field in the YAML frontmatter.

Functions

Function names describe what the function does, in verb form:

  • fetchJSON(url) — fetches and returns JSON
  • toTagName(key) — converts a key to a tag name
  • clearFieldset(el) — clears a fieldset

Not:

  • helper(), process(), handle() — vague
  • oklchHelper() — implementation in the name

CSS custom properties

CSS custom property names use double-hyphen prefix (CSS spec), then describe the concern:

  • --surface-1, --surface-2, --surface-3 — semantic surface levels
  • --text-1, --text-2 — semantic text levels
  • --accent — the brand accent
  • --transition-duration, --transition-property, --transition-timing-function

Not:

  • --blue-500, --red-700 — color name in the variable; if the brand changes, the name lies
  • --my-special-color — vague

Cross-file references

Cross-file references in documentation are text references, not symlinks. Always:

See `references/state-machines.md` for the canonical pattern.

Never:

references/state-machines.md → ../html/references/state-machines.md   (symlink)

Reasoning: text references are visible in any file viewer, survive copy/paste, and produce no surprise file system behavior. Symlinks are invisible context that breaks portability.

What naming never does

  • Never names by implementation detail
  • Never names by adjective stack (modern-, semantic-, accessible-)
  • Never embeds a value in a name (--color-blue is bad; the value is oklch(...), the concern is "brand")
  • Never uses ambiguous names (utils.js, helper(), data)
  • Never relies on symlinks for cross-file references

Baseline & support

Checked against MDN as of 2026-07-16.

  • No version-sensitive web-platform features are referenced here — everything used is Baseline Widely available.

Canonical rules: https://github.com/Autocss-com/ai/blob/main/AGENTS.md

References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free