Build a Token Naming Audit Skill for Claude Code

Your token file has 412 entries. Half of them are named color.background.primary. The other half are colorBgPrimary, bg-primary-1, or worse, blue-2. You know there is drift. You just do not have three hours to scroll through a JSON file looking for it.

This guide gives you a Claude Code skill that does the scrolling for you. Drop one file into your skills folder, type /audit-token-naming, and walk away with a markdown report of every token that breaks your convention plus a suggested fix for each one.

The SKILL.md

Copy this whole block into a new file. I will tell you where to put it in the next section.

---
name: audit-token-naming
description: Audit every design token in the project against the team naming
  convention. Use when the user mentions tokens, naming, naming convention,
  token audit, or runs /audit-token-naming. Outputs a markdown report with
  issues and suggested fixes.
---

# Token Naming Audit

You are auditing design tokens against a naming convention. Be specific,
quote the exact token name in every finding, and always suggest a fix.

## Step 1: Find the convention

Look for a naming convention file in this order:

1. `.design-system/naming-conventions.md`
2. `docs/tokens/naming.md`
3. `tokens/README.md`
4. `CONTRIBUTING.md` (search for "token" or "naming")

If none exist, default to this convention:

```
{category}.{intent}.{modifier?}.{scale?}

category: color | spacing | typography | radius | shadow | motion | size | z
intent:   background | foreground | border | surface | text | action | feedback
modifier: primary | secondary | tertiary | success | warning | danger | info
scale:    xs | sm | md | lg | xl | 2xl | 3xl
```

Casing: lowercase, dot notation between segments, kebab-case within a segment
when needed (e.g. `color.background.action-primary`).

## Step 2: Find the tokens

Search these paths in order:

1. `tokens/**/*.json`
2. `src/tokens/**/*.json`
3. `styles/tokens/**/*.{json,yaml,yml}`
4. `design-tokens/**/*.json`
5. CSS custom properties in `**/*.css` (variables starting with `--`)

Read every file. Build a flat list of token names.

## Step 3: Check each token

For each token, flag any of these issues:

| Code | Issue | Example bad | Example good |
|------|-------|-------------|--------------|
| `case` | Uses camelCase or snake_case instead of dot notation | `colorBgPrimary`, `color_bg_primary` | `color.background.primary` |
| `no-category` | Missing a clear category prefix | `primary-1`, `bg-blue` | `color.background.primary` |
| `vague-modifier` | Uses generic numbered or color-named modifiers | `button-1`, `blue-2`, `gray-3` | `action.primary`, `surface.subtle` |
| `mixed-abbrev` | Mixes abbreviated and full words across the file | `md` and `medium` in same file | Pick one, use everywhere |
| `mixed-separator` | Mixes dots, slashes, dashes between segments | `color/bg/primary` next to `color.bg.primary` | Pick one separator |
| `primitive-leak` | Primitive token used where a semantic should live | `blue.500` in a button background slot | Alias to `color.background.action` |

## Step 4: Output the report

Write a single markdown report to the chat. Use this exact structure:

```markdown
# Token Naming Audit

**Files scanned:** {count}
**Tokens checked:** {count}
**Issues found:** {count}
**Convention source:** {file path or "default"}

## Summary

| Severity | Count |
|----------|-------|
| Error    | {n}   |
| Warning  | {n}   |
| Info     | {n}   |

## Errors

| Token | Issue | Suggested fix |
|-------|-------|---------------|
| `colorBgPrimary` | case: camelCase, expected dot notation | `color.background.primary` |
| `blue-2` | vague-modifier: scale without intent | `color.background.action.secondary` |

## Warnings

| Token | Issue | Suggested fix |
|-------|-------|---------------|
| `spacing-md` and `spacing-medium` | mixed-abbrev: pick one | Standardize on `md` |

## Info

| Token | Issue | Note |
|-------|-------|------|
| `z.modal` | OK, but no z-scale documented | Consider adding `z.toast`, `z.popover` |

## Quick wins

The five highest-impact renames, ordered by how many places they appear.
```

## Rules for fixes

- Always preserve the **value** of the token. Only suggest a name change.
- If a token is referenced elsewhere (CSS, components, docs), say so:
  "Used in 14 files. Rename will require a find-and-replace."
- Never suggest deleting tokens. Suggest deprecation only.
- If you are not sure what a token represents, ask before flagging it.

## When to skip

- Auto-generated files (`*.generated.json`, `dist/`, `build/`)
- Vendor or third-party token files inside `node_modules/`
- Files explicitly marked `// audit:skip` at the top

How to install this skill

You have two options. Pick based on who needs it.

Personal (just for you, available in every project):

mkdir -p ~/.claude/skills/audit-token-naming
nano ~/.claude/skills/audit-token-naming/SKILL.md

Paste the block above, save, done.

Team (shared via git, lives with the project):

mkdir -p .claude/skills/audit-token-naming
nano .claude/skills/audit-token-naming/SKILL.md
git add .claude/skills/audit-token-naming
git commit -m "Add token naming audit skill"

Now anyone on your team who pulls the repo gets the skill automatically.

Example invocations

The skill triggers on the slash command or on natural language. All of these work:

/audit-token-naming

Audit my tokens for naming issues

Check the token files against our naming convention

Find every token that does not match category.intent.modifier

If you want the skill to only run on explicit slash command (no auto-trigger), add invocation: user to the frontmatter.

What it actually does

Walk through the logic so you know what to expect.

1. Locates your convention. It checks four common file paths. If your team has a written rule, the skill uses it. If not, it falls back to a sensible default so you still get a useful report.
2. Reads every token file. It does not stop at JSON. It also picks up YAML and CSS custom properties, which catches teams that have tokens in more than one format.
3. Builds a flat list. Tokens get flattened into dot-notation names so a deeply nested JSON like { color: { background: { primary: "#fff" } } } becomes color.background.primary for comparison.
4. Runs six checks. Each token gets validated against six rules. The rules cover the most common drift patterns I see across audits: casing, missing categories, vague names, abbreviation mixing, separator chaos, and primitive leaks.
5. Outputs a markdown report. Three sections by severity. Quick wins at the bottom so you know where to start.

The output is markdown so you can paste it into a Notion doc, a Linear ticket, or a Slack message without reformatting.

Customize for your team

The defaults are a starting point. Here is what to tweak.

Change the default convention. If your team writes tokens as color-bg-primary (kebab, no dots), edit the convention block in Step 1. Replace the dot-notation pattern with your actual format.

Add custom categories. If you have categories like elevation, opacity, or breakpoint, add them to the category list.

Change the search paths. If your tokens live in packages/design-tokens/src/, add that path to Step 2. Remove paths you do not use.

Add team-specific issues. If your team has a rule like “all spacing tokens must use the 4px grid”, add it to the table in Step 3:

| `off-grid` | Spacing value not divisible by 4 | `spacing.gap.13px` | `spacing.gap.12px` or `spacing.gap.16px` |

Tighten the output. If you only care about errors, remove the Warnings and Info sections from the report template.

Add a budget. Append a rule: “If error count is over 50, output only the top 20 by frequency.”

What you get

After 20 minutes of setup and 30 seconds of running:

• A reusable skill that runs on any project with tokens
• A standardized audit format your team can rely on
• A starting list of fixes ranked by impact
• Zero copy-pasted prompts. Just one slash command.

The skill compounds. Every project you open, every PR you review, every onboarding session: same audit, same format.

Common pitfalls

Skill does not trigger. Check the name field in frontmatter matches the slash command. name: audit-token-naming means /audit-token-naming. Underscores will not work.

Reads the wrong files. If your tokens live somewhere unusual, the skill will not find them. Add your path explicitly to Step 2 or pass the path in your prompt: /audit-token-naming in packages/tokens/.

Too many false positives. If your team uses blue.500 intentionally as a primitive (in a primitives-only file), the primitive-leak rule will flag it. Add an exception: “Skip files matching *primitives* or *core*.”

Output too long. Token files with 500+ entries produce big reports. Tell Claude to “summarize errors and only show the top 20 with full detail” or split the audit by category.

Convention drift inside the convention. If your naming-conventions.md is itself outdated, the skill will faithfully audit against the wrong rules. Audit the convention doc once a quarter.

Exercise

Install the skill and run it on a real token file

15 min

1. Install the skill in your home folder

   Open a terminal and run mkdir -p ~/.claude/skills/audit-token-naming followed by nano ~/.claude/skills/audit-token-naming/SKILL.md. Paste the SKILL.md block from this guide, save, and close. Verify the file with cat ~/.claude/skills/audit-token-naming/SKILL.md.

   • cat prints the full SKILL.md with the frontmatter name: audit-token-naming
   • The folder name matches the slash command exactly (underscores or typos will break the trigger)
   • No YAML errors on the first --- block

2. Run /audit-token-naming against your repo

   Navigate to a repo with real tokens. Start Claude Code. Type /audit-token-naming. Read the report. If the skill cannot find your token files, pass the path explicitly: /audit-token-naming in packages/design-tokens/.

   • The report lists the exact file paths and token counts at the top
   • Errors, warnings, and info are split into three tables, not one wall of text
   • At least one quick win at the bottom is a rename you would actually do this sprint