cso

claude-skills-organizer

English | 中文

A Claude Code plugin that manages user skills and plugins in a three-tier hierarchy to reduce context noise.

Problem

As you install more Claude Code skills and plugins, every skill's description is loaded into every conversation — even skills you rarely use. With 50-100+ skills across user skills and plugins, this adds noise to Claude's context, interferes with skill matching, and degrades model performance.

Quick Start

/plugin marketplace add tidego/claude-skills-organizer
/plugin install cso

Once installed, the plugin works fully automatically — no extra setup needed. Usage tracking hooks start recording immediately, and tiers adjust dynamically based on your actual usage patterns. For manual control, see the Usage section below, but automatic tracking already handles most scenarios including dynamic promotion and demotion.

All features have been fully tested — including tier rebalancing, pin/unpin, promote/demote, rollback, clean, and 30-day usage simulation.

Solution

This plugin automatically archives rarely-used skills and plugins based on usage patterns:

User skills are archived by toggling disable-model-invocation: true in their SKILL.md frontmatter:

• Stay in ~/.claude/skills/ — no files are moved
• Keep their /skill-name command — you can still invoke them directly
• Are removed from Claude's auto-matching — less noise, better matching

Plugins are treated as a whole unit — all skill reads within a plugin are aggregated:

• Archived by setting enabledPlugins to false in ~/.claude/settings.json
• Can be re-enabled instantly when needed
• Same tier rules apply (3+ reads → T1, 1-2 → T2, 0 → T3)

Three Tiers

Tier	State	Loaded?	Criteria (15-day window)
T1 (active)	No frontmatter flag	Always	3+ reads
T2 (warm)	disable-model-invocation: true	On / invoke	1-2 reads
T3 (cold)	disable-model-invocation: true	On / invoke	0 reads

Hierarchical Index — Claude Can Dig Deeper

The plugin maintains a two-level index so Claude can progressively discover archived skills:

T1 Index (always loaded in context)
  └── Lists T2 warm skills with descriptions
        └── Points to T2 Index file
              └── T2 Index (read on demand)
                    └── Lists T3 cold skills with descriptions

• T1 index (skills-organize/SKILL.md): Always in Claude's context. Shows T2 skills and plugins + a pointer to the T2 index.
• T2 index (~/.claude/skills-archive/t2-index.md): Read by Claude on demand when it needs a cold skill or plugin. Lists all T3 entries.

This means Claude can proactively discover archived skills when your request matches a description in the index — no need to remember exact skill names.

Usage

Slash Command

/cso:skills-organize              # Dry-run: show what would change
/cso:skills-organize --apply       # Execute tier changes
/cso:skills-organize --stats       # Show usage statistics

Pin / Unpin

/cso:skills-organize --pin my-skill          # Keep a skill always in T1
/cso:skills-organize --pin plugin:my-plugin  # Keep a plugin always in T1
/cso:skills-organize --unpin my-skill        # Remove pin

Force Promote / Demote

/cso:skills-organize --promote my-skill --apply   # Activate (remove archive flag)
/cso:skills-organize --demote my-skill --apply     # Archive (add flag)

Clean (Destructive)

/cso:skills-organize --clean              # Preview: show what would be deleted
/cso:skills-organize --clean --apply      # Delete all T2/T3 skills, disable T2/T3 plugins

Custom Window

/cso:skills-organize --window 7              # Use 7-day window instead of default 15
/cso:skills-organize --window 30 --apply     # Apply with 30-day window

The --window parameter sets the usage window in days (default: 15). Skills with no reads within this window get archived. A shorter window archives more aggressively; a longer window keeps more skills active.

Rollback

/cso:skills-organize --rollback    # Undo last organize

How It Works

Automatic Tracking

Three hooks silently record skill usage:

• Skill hook (PreToolUse:Skill): Fires when Claude autonomously invokes a skill (plugin skills like /plugin:skill are aggregated by plugin)
• Read hook (PreToolUse:Read): Fires when Claude reads a SKILL.md file (plugin skill reads are aggregated by plugin)
• Prompt hook (UserPromptSubmit): Fires when you manually type /skill-name — detects the command, validates it against installed skills/plugins, and records usage

Usage data is stored in ~/.claude/skills-archive/usage-stats.json.

Tier Rebalancing

When you run /cso:skills-organize --apply: