ruleset-optimization

name	ruleset-optimization
description	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.

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