Rules Builder

Interactive skill for creating and managing Claude Code modular rules using guided elicitation with AskUserQuestion.

When to Use

User wants to create a new rule file
User wants to edit or delete an existing rule
User wants to list or view existing rules
User mentions .claude/rules/
User asks about path-specific rules or glob patterns
User wants to organize project instructions
User wants personal rules across all projects

Elicitation Approach

Use AskUserQuestion throughout the workflow to guide the user through all available options. Present relevant choices based on context and let the user shape the rule configuration step by step.

What Can Be Done with Rules

Rule Scope Options

Scope	Description
Global	Applies to all files in the project (no `paths` frontmatter)
Path-specific	Only applies to files matching glob patterns

Rule Locations

Location	Path	Applies To
User-level	`~/.claude/rules/`	All your projects (personal preferences)
Project root	`.claude/rules/`	Current project only
Subdirectory	`.claude/rules/frontend/`	Current project, organized by domain
Subdirectory	`.claude/rules/backend/`	Current project, organized by domain

Priority: User-level rules load first, project rules load after and can override.

Glob Pattern Options

Pattern	Matches
`*/.ts`	All TypeScript files
`*/.{ts,tsx}`	TypeScript and React files
`src/*/`	All files under src/
`src/api/*/.ts`	API files only
`*/.{test,spec}.ts`	Test files only
`*.config.{js,ts,json}`	Config files in root
`{src,lib}/*/.ts`	Multiple directories

See ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/references/glob-patterns.md for complete reference.

Rule Categories

Common categories to organize rules:

Code style and formatting
Testing conventions
Security requirements
API development patterns
Documentation standards
Performance guidelines
Framework-specific rules (React, Node, etc.)

Frontmatter Options

Valid YAML frontmatter fields:

---
paths: "src/**/*.ts"        # Glob pattern(s) - string or array
description: "API rules"    # Optional description (max 200 chars)
priority: 75                # Optional priority 0-100 (default 50)
enabled: true               # Optional enable/disable (default true)
---

Validate against schema: ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/schemas/rule-frontmatter.schema.json

Available Operations

Operation	Description
Create	New rule file with guided configuration
Edit	Modify existing rule (scope, content, frontmatter)
Delete	Remove a rule file
List	Show all rules in project or user directory
Validate	Check frontmatter against schema
Move	Change rule location (project ↔ user-level)

Workflow

Determine intent - Create, edit, delete, or list rules
Elicit configuration - Use AskUserQuestion to gather:
- Rule scope (global vs path-specific)
- Target files (glob patterns)
- Location (user-level vs project)
- Category and filename
- Initial content suggestions
Generate/modify file - Create or edit the rule with proper frontmatter
Validate - Check frontmatter against JSON schema
Confirm - Show result and offer next actions

User-Level Rules

Personal rules in ~/.claude/rules/ apply to all projects:

~/.claude/rules/
├── preferences.md    # Personal coding preferences
├── workflows.md      # Preferred workflows
└── shortcuts.md      # Personal shortcuts

Use cases:

Consistent style across all projects
Personal workflow reminders
Default behaviors that projects can override

Organizing Rules

By Domain (Subdirectories)

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

By Scope (Path-Specific)

---
paths: src/api/**/*.ts
---
# API Rules

Symlinks for Shared Rules

ln -s ~/shared-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

Best Practices

Keep rules focused - One topic per file
Use descriptive filenames - code-style.md not rules1.md
Use conditional rules sparingly - Only when truly path-specific
Organize with subdirectories - Group related rules
Be specific - "Use 2-space indentation" not "Format properly"
Review periodically - Update as project evolves

Listing Rules

To show all available rules from both user-level and project directories:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/scripts/list_rules.py [project_path]

Examples:

# List rules for current directory
python3 ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/scripts/list_rules.py

# List rules for specific project
python3 ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/scripts/list_rules.py /path/to/project

Output includes:

User-level rules from ~/.claude/rules/
Project rules from <project>/.claude/rules/
For each rule: name, path, description, glob patterns, scope, priority, enabled status

Validation

Before saving, validate frontmatter against the JSON schema:

Field	Type	Constraints
`paths`	string or string[]	Valid glob pattern(s)
`description`	string	Max 200 characters
`priority`	integer	0-100, default 50
`enabled`	boolean	default true

References

Glob patterns: ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/references/glob-patterns.md
Frontmatter schema: ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/schemas/rule-frontmatter.schema.json
List rules script: ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/scripts/list_rules.py
Validate script: ${CLAUDE_PLUGIN_ROOT}/skills/rules-builder/scripts/validate_frontmatter.py

Examples

Create API-specific rules

User: "I want rules for my API endpoints"
-> Elicit scope, patterns, location, category
-> Create .claude/rules/api.md with paths: src/api/**/*.ts

Edit existing rule scope

User: "Update testing rules to include integration tests"
-> List rules, elicit selection
-> Show current config, elicit changes
-> Update paths to **/*.{test,spec,integration}.ts

Create personal preferences

User: "Add my coding preferences for all projects"
-> Elicit location (user-level)
-> Create ~/.claude/rules/preferences.md

Organize by domain

User: "Organize my frontend rules"
-> Elicit subdirectory structure
-> Create .claude/rules/frontend/ with react.md, styles.md

List all rules

User: "Show me all my rules"
-> Run list_rules.py script
-> Display user-level and project rules with metadata
-> Offer to edit, delete, or create new rules

rules-builder