| name | description |
|---|---|
claude-rules-builder |
Creates and iteratively refines .claude/rules/*.md files — scoped instruction files that only load when Claude reads matching files. Use this skill when the user wants to create a Claude rule, scope instructions to specific file types or directories, reduce CLAUDE.md bloat, move file-specific sections out of CLAUDE.md into rule files, or asks about .claude/rules/. Also trigger when the user says "make a rule for X files", "add rules for my components", "move this to a rule file", "rules for TypeScript", or any mention of path-scoped rules. |
Rules in .claude/rules/ are focused instruction files that load only when Claude reads matching files — keeping your main CLAUDE.md lean and reducing noise. This skill helps you create them well.
A rule file is a markdown file with optional YAML frontmatter scoping it to specific paths:
---
paths:
- "src/api/**/*.ts"
---
# API Handler Rules
- Validate all inputs at the route level before passing to services
- Return errors using the standard `ApiError` class, not plain throwsWithout paths, the rule loads every session (same as CLAUDE.md). With paths, it only loads when Claude opens a matching file — so you can have detailed framework-specific guidance without cluttering every session.
Start by understanding:
- What files does it cover? (a directory, a file extension, a pattern like
*.test.ts) - What instructions belong here? (things only relevant when working with those files)
- Is this new content or a migration? (pulling existing content out of CLAUDE.md)
If the user says "create a rule for TypeScript files", that's enough to start. If they say "make some rules", ask a focused question: "What kind of files or directory should this rule apply to?"
Pick a descriptive filename (typescript.md, api-handlers.md, react-components.md).
Write the frontmatter with appropriate globs, then the rule body. Aim for 3–10 bullets, each specific and verifiable. Place it at .claude/rules/<name>.md.
Present the draft clearly and ask: "Does this look right? Anything missing or off?" Iterate until the user is satisfied. Good rules are short — if it's growing past 15 lines of instructions, consider splitting by concern.
| Goal | Pattern |
|---|---|
| All TypeScript | **/*.ts |
| TypeScript + TSX | **/*.{ts,tsx} |
| Specific directory | src/api/**/* |
| Test files | **/*.test.{ts,js} |
| Root markdown only | *.md |
| Multiple dirs | use multiple paths entries |
You can also use brace expansion: src/**/*.{ts,tsx,js,jsx} matches all JS/TS variants at once.
When the goal is reducing CLAUDE.md bloat:
- Read the current CLAUDE.md
- Identify sections that are file-type or directory specific — these are candidates
- For each, propose: rule name, glob pattern, and which lines to move
- Create the rule files, then remove the migrated content from CLAUDE.md
- Optionally leave a comment:
<!-- See .claude/rules/typescript.md -->
The goal is that CLAUDE.md stays under ~100 lines of general project context, with file-specific detail living closer to where it's relevant.
Rules load into the same context window as your conversation, so brevity matters. A tight, specific rule that Claude actually follows beats a long one that gets lost.
Specific and verifiable: "Use ApiError for all thrown errors in handlers" beats "handle errors properly."
File-scoped by nature: If an instruction only matters when editing .rs files, it belongs in a Rust rule — not CLAUDE.md.
One topic per file: Don't mix TypeScript style rules with API design rules. Separate files are easier to maintain and clearer to Claude about their scope.
.claude/rules/rust.md:
---
paths:
- "src-tauri/**/*.rs"
---
# Rust Rules
- Run `cargo check` before suggesting the user test changes
- Prefer `thiserror` for error types; avoid `unwrap()` in library code
- All public functions in `core/` must work without Tauri dependencies (testability)
- Use the `FileSystem` trait for file operations — never call `std::fs` directly