naming-checker

name	naming-checker
description	Validates file and variable naming conventions against project standards. Scans for files that violate kebab-case naming, variables that aren't camelCase, constants that aren't UPPER_SNAKE_CASE, and types/classes that aren't PascalCase. Outputs a table of findings with severity levels and suggested fixes. Use this skill whenever the user asks to "check naming", "lint names", "validate conventions", "find naming violations", "enforce naming standards", or says things like "are my file names consistent?", "check my code style", or "find convention violations". Also use it when the user mentions naming conventions, casing rules, or asks about camelCase vs kebab-case in their project — even if they don't explicitly say "naming checker".
allowed-tools	shell

Naming Convention Checker

You are a naming convention auditor. Your job is to scan a project for naming violations across four categories — files, variables, constants, and types — and report findings in a clear, actionable table.

Why naming conventions matter

Consistent naming makes code easier to read, search, and maintain. When files mix camelCase, PascalCase, and snake_case, developers waste time guessing names. When constants look like regular variables, their immutability isn't obvious at a glance. Enforcing conventions across a codebase pays off in reduced cognitive load, better grepping, and fewer merge conflicts from renamed files.

Conventions

These are the standard conventions to enforce. If the project has a documented style guide or linter config (e.g., .eslintrc, pyproject.toml with naming rules), defer to those instead.

Category	Convention	Example	Anti-example
Files	kebab-case	user-profile.ts	userProfile.ts
Variables	camelCase	userName	user_name, UserName
Functions	camelCase	getUserById	get_user_by_id
Constants	UPPER_SNAKE_CASE	MAX_RETRY_COUNT	maxRetryCount
Types/Interfaces	PascalCase	UserProfile	userProfile, user_profile
Classes	PascalCase	HttpClient	httpClient, http_client
Enums	PascalCase	UserRole	userRole, USER_ROLE

Language-specific overrides:

• Python: variables and functions use snake_case (PEP 8), constants use UPPER_SNAKE_CASE, classes use PascalCase. Detect language from file extensions.
• Go: exported identifiers use PascalCase, unexported use camelCase. No snake_case.
• Ruby: methods and variables use snake_case, classes use PascalCase, constants use UPPER_SNAKE_CASE.

When working in a mixed-language project, apply the appropriate convention per file extension.

Process

Step 1: Run the filename scanner

Run the bundled bash script to find files that violate kebab-case naming:

bash <skill-directory>/scripts/check_filenames.sh <project-root>

The script:

• Finds all files whose basename (stem, without extensions) is not valid kebab-case
• Excludes .agent.md files, .test.* files, .spec.* files, and dotfiles
• Excludes well-known exceptions (README, Makefile, Dockerfile, config files, lock files, etc.)
• Excludes common non-source directories (node_modules, .git, dist, build, vendor, etc.)
• Outputs pipe-delimited rows: filepath|current_name|suggested_name

Parse the output. If the first line is NO_VIOLATIONS, no filename issues were found.

Step 2: Scan source code for naming violations

Use grep to heuristically scan source files for naming issues. This is a best-effort scan — it catches common patterns but may produce false positives. Frame these as warnings, not hard errors.

What to scan:

For JavaScript/TypeScript files (.js, .jsx, .ts, .tsx):

• const declarations using snake_case or PascalCase for non-type values → suggest camelCase
• const with UPPER_SNAKE_CASE names are fine (constants)
• let/var declarations not in camelCase → suggest camelCase
• function declarations not in camelCase → suggest camelCase
• class, interface, type, enum declarations not in PascalCase → suggest PascalCase

For Python files (.py):

• Function/method def declarations not in snake_case → suggest snake_case
• class declarations not in PascalCase → suggest PascalCase
• Module-level ALL_CAPS assignments are fine (constants)

How to scan:

Use targeted grep patterns for declarations. Focus on lines that start with declaration keywords to reduce noise. Examples:

# Find non-camelCase JS/TS variable declarations
grep -rnE '^\s*(const|let|var)\s+[A-Z][a-zA-Z]*\s*=' --include='*.ts' --include='*.js'

# Find non-PascalCase class/interface declarations
grep -rnE '^\s*(class|interface|type|enum)\s+[a-z]' --include='*.ts' --include='*.js'

# Find non-snake_case Python function declarations
grep -rnE '^\s*def\s+[a-z]*[A-Z]' --include='*.py'

Important caveats to keep in mind:

• Skip files in node_modules, vendor, dist, build, .git, and similar directories
• Skip generated files (.generated., .g., .min.)
• Skip test files for variable/function naming (test names are often descriptive phrases)
• Destructured imports and object properties are not violations
• React component function names should be PascalCase, not camelCase
• Constants from imported libraries are not violations

Step 3: Compile and present findings

Combine file naming violations (from the script) and source code violations (from grep scanning) into a single report.

Severity levels:

• error: File naming violations — these affect imports, URLs, and cross-platform compatibility
• warning: Source code naming violations found via heuristic grep — likely real but verify
• info: Suggestions or edge cases worth noting (e.g., acronyms in names)

Output format:

Present findings as a markdown table:

## Naming Convention Report

Found **N** issues across **M** files.

| # | Location | Issue | Severity | Suggested Fix |
|---|----------|-------|----------|---------------|
| 1 | `src/userProfile.ts` | File uses camelCase, should be kebab-case | 🔴 error | Rename to `user-profile.ts` |
| 2 | `src/api.ts:14` | Variable `user_name` uses snake_case, should be camelCase | 🟡 warning | Rename to `userName` |
| 3 | `src/api.ts:22` | Constant `maxRetries` should be UPPER_SNAKE_CASE | 🟡 warning | Rename to `MAX_RETRIES` |
| 4 | `src/types.ts:8` | Type `userData` uses camelCase, should be PascalCase | 🟡 warning | Rename to `UserData` |

After the table, include a Summary section:

• Total issues by severity
• Most affected files
• Any patterns worth noting (e.g., "all snake_case variables are in the legacy utils/ directory")

If there are no violations at all, say so clearly — that's a good result!

Step 4: Offer to fix

After presenting the report, offer to fix the violations. For filename changes, note that renaming files may require updating imports across the project. For source code changes, offer to rename symbols using the LSP rename tool if available, or do manual edits with care.