Ruleset Optimization Guidelines
Auto-activate when: Working with CLAUDE.md, settings.json, SKILL.md files, .claude/ directory, or when user mentions ruleset optimization, context efficiency, skill extraction, token savings, or improving Claude Code configuration.
This skill provides comprehensive guidelines for optimizing Claude rulesets to minimize context usage while maximizing effectiveness.
Context Efficiency Philosophy
PRIMARY GOAL: Minimize baseline context, maximize signal-to-noise ratio.
Core Strategy:
- Skills for domain-specific rules (git, python, web, containers): auto-load when relevant, 30-70% context reduction when inactive
- CLAUDE.md minimal: project overview, quick start, project-specific patterns, skill references only
- Progressive disclosure: baseline=always-needed (
20%), details=on-demand via skills (80%)
Decision Framework
Extraction Decision Tree
Is content >200 tokens?
├─ No → Keep in CLAUDE.md
└─ Yes → Is it procedural?
├─ No → Keep in CLAUDE.md (policy)
└─ Yes → Is it used <70% of sessions?
├─ No → Keep in CLAUDE.md (always needed)
└─ Yes → Extract to skill (saves tokens)
Move to Skills (Procedural "How-To")
- Step-by-step procedures, domain workflows, tool patterns, decision trees
- Language/framework-specific rules, optional best practices
Keep in CLAUDE.md (Policy "What/Why")
- Core values, always-applicable preferences, security requirements
- File operation policies, communication style, project overview
Token Savings Calculation
Formula: tokens × (1 - usage_frequency)
Priority thresholds:
- High: 500+ tokens, used <50% of time
- Medium: 200-500 tokens, used <30% of time
- Low: <200 tokens or used >70% of time
Report format:
- Before: X tokens baseline
- After: Y tokens baseline, Z with skills (when needed)
- Savings: (X - Y) tokens baseline (N% reduction)
Deduplication Strategy
Personal vs Project Rulesets:
- Personal (~/.claude/CLAUDE.md): universal defaults
- Project (.claude/CLAUDE.md): project-specific overrides, takes precedence
- Never duplicate between them
Across Skills:
- Clear, non-overlapping scope per skill
- Reference other skills vs duplicating content
Creating Effective Skills
Structure Template
---
name: skill-name
description: Clear description of when to activate and what it contains.
---
# Skill Title
Brief introduction and purpose.
## Core Content
[Domain-specific guidance]
Activation Patterns
Auto-activation triggers:
- File patterns: .py, package.json, Dockerfile
- Git operations: commit, push, version control
- Project structure: directories, files present
Manual invocation:
- Slash commands: /optimize-prompt, /commit
- Explicit requests: "optimize this ruleset"
Anti-Patterns
- Over-extraction: No skills for <100 tokens
- Under-referencing: Always add reference when removing content
- Duplication: Never duplicate between personal/project or across skills
- Poor organization: Don't mix domains in one skill
Optimization Impact Examples
Before: 6,000 tokens baseline (all loaded)
After: 4,000 tokens baseline + 1,500 tokens in skills (selective)
Result: 33% baseline reduction, 25-33% typical session savings
Compound benefits:
- Optimization helps ALL projects using shared skills
- Clearer organization improves maintainability
- Faster context loading and better reasoning
- More room for project-specific context
Maintenance Guidelines
Regular Review
- Quarterly token usage review
- Check for new extraction opportunities
- Verify skill activation patterns
- Remove stale or unused skills
Skill Evolution
- Update content as practices evolve
- Merge overlapping skills
- Split skills >1000 tokens
- Archive deprecated skills with notes
This skill is manually invoked when optimizing rulesets or organizing Claude instructions.
For command usage, see:
/optimize-ruleset - Analyze and optimize current ruleset/analyze-permissions - Review permission patterns
1---2name: ruleset-optimization3description: Guidelines for optimizing Claude rulesets and instruction files (CLAUDE.md, settings.json) using context efficiency principles. Includes strategies for skill extraction, progressive disclosure, token savings calculation, and deduplication. Manually invoke when optimizing rulesets, reducing context size, extracting content to skills, or improving ruleset organization.4---5
6# Ruleset Optimization Guidelines
7
8**Auto-activate when:** Working with `CLAUDE.md`, `settings.json`, `SKILL.md` files, `.claude/` directory, or when user mentions ruleset optimization, context efficiency, skill extraction, token savings, or improving Claude Code configuration.
9
10This skill provides comprehensive guidelines for optimizing Claude rulesets to minimize context usage while maximizing effectiveness.
11
12## Context Efficiency Philosophy
13
14**PRIMARY GOAL**: Minimize baseline context, maximize signal-to-noise ratio.
15
16**Core Strategy:**
17- **Skills for domain-specific rules** (git, python, web, containers): auto-load when relevant, 30-70% context reduction when inactive
18- **CLAUDE.md minimal**: project overview, quick start, project-specific patterns, skill references only
19- **Progressive disclosure**: baseline=always-needed (~20%), details=on-demand via skills (~80%)
20
21## Decision Framework
22
23### Extraction Decision Tree
24```
25Is content >200 tokens?
26├─ No → Keep in CLAUDE.md
27└─ Yes → Is it procedural?
28 ├─ No → Keep in CLAUDE.md (policy)
29 └─ Yes → Is it used <70% of sessions?
30 ├─ No → Keep in CLAUDE.md (always needed)
31 └─ Yes → Extract to skill (saves tokens)
32```
33
34### Move to Skills (Procedural "How-To")
35- Step-by-step procedures, domain workflows, tool patterns, decision trees
36- Language/framework-specific rules, optional best practices
37
38### Keep in CLAUDE.md (Policy "What/Why")
39- Core values, always-applicable preferences, security requirements
40- File operation policies, communication style, project overview
41
42### Token Savings Calculation
43**Formula:** tokens × (1 - usage_frequency)
44
45**Priority thresholds:**
46- High: 500+ tokens, used <50% of time
47- Medium: 200-500 tokens, used <30% of time
48- Low: <200 tokens or used >70% of time
49
50**Report format:**
51- Before: X tokens baseline
52- After: Y tokens baseline, Z with skills (when needed)
53- Savings: (X - Y) tokens baseline (N% reduction)
54
55## Deduplication Strategy
56
57**Personal vs Project Rulesets:**
58- Personal (~/.claude/CLAUDE.md): universal defaults
59- Project (.claude/CLAUDE.md): project-specific overrides, takes precedence
60- Never duplicate between them
61
62**Across Skills:**
63- Clear, non-overlapping scope per skill
64- Reference other skills vs duplicating content
65
66## Creating Effective Skills
67
68### Structure Template
69```markdown
70---
71name: skill-name
72description: Clear description of when to activate and what it contains.
73---
74
75# Skill Title
76
77Brief introduction and purpose.
78
79## Core Content
80[Domain-specific guidance]
81```
82
83### Activation Patterns
84**Auto-activation triggers:**
85- File patterns: .py, package.json, Dockerfile
86- Git operations: commit, push, version control
87- Project structure: directories, files present
88
89**Manual invocation:**
90- Slash commands: /optimize-prompt, /commit
91- Explicit requests: "optimize this ruleset"
92
93### Anti-Patterns
94- Over-extraction: No skills for <100 tokens
95- Under-referencing: Always add reference when removing content
96- Duplication: Never duplicate between personal/project or across skills
97- Poor organization: Don't mix domains in one skill
98
99## Optimization Impact Examples
100
101**Before:** 6,000 tokens baseline (all loaded)
102**After:** 4,000 tokens baseline + 1,500 tokens in skills (selective)
103**Result:** 33% baseline reduction, 25-33% typical session savings
104
105**Compound benefits:**
106- Optimization helps ALL projects using shared skills
107- Clearer organization improves maintainability
108- Faster context loading and better reasoning
109- More room for project-specific context
110
111## Maintenance Guidelines
112
113### Regular Review
114- Quarterly token usage review
115- Check for new extraction opportunities
116- Verify skill activation patterns
117- Remove stale or unused skills
118
119### Skill Evolution
120- Update content as practices evolve
121- Merge overlapping skills
122- Split skills >1000 tokens
123- Archive deprecated skills with notes
124
125---
126
127**This skill is manually invoked when optimizing rulesets or organizing Claude instructions.**
128
129For command usage, see:
130- `/optimize-ruleset` - Analyze and optimize current ruleset
131- `/analyze-permissions` - Review permission patterns
majiayu000