Deduplicate and optimize your agent skills.
Agent skills accumulate fast. Install a few collections from openskills, skills.sh, or skillshare and you end up with 100+ skills competing for context.
We ran skill-compact against a real collection of 120 installed skills and found:
| Metric | Value |
|---|---|
| Total SKILL.md lines | 25,874 |
| Estimated tokens | ~222,000 |
| Skills with duplicated content | 16 across 4 clusters |
| Shared boilerplate in worst cluster | ~30-40% copy-pasted verbatim |
When skills come from different authors or collections, they often duplicate shared patterns — identical assessment templates, copy-pasted best-practice lists, repeated boilerplate sections. That's context budget burned on redundancy.
skill-compact finds the duplication, suggests a strategy, and lets your agent do the rewriting. No separate API key needed — the tool is itself a skill, and the hosting agent is the LLM.
# Copy into your skills directory
git clone https://github.com/JuanJoseGonGi/skill-compact.git
cp -r skill-compact ~/.claude/skills/skill-compact
# Or install via skills.sh / openskills
npx skills add JuanJoseGonGi/skill-compact
npx openskills install JuanJoseGonGi/skill-compactThen tell your agent: "Compact my skills"
The agent reads SKILL.md, runs the scripts, and walks you through each compaction decision.
skill-compact is an agentskills.io-compliant skill. There's no CLI binary to run — your agent (Claude Code, Cursor, Gemini CLI, OpenCode, Codex, etc.) loads the skill and executes the workflow:
Agent loads SKILL.md
|
v
Phase 1: scan.ts --> JSON inventory of all skills (lines, tokens, structure)
Phase 2: group.ts --> Clusters by keyword similarity (Jaccard), suggests strategies
Phase 3: backup.ts --> Timestamped snapshot before any changes
compact --> Agent reads prompt templates, generates compacted output
write-compact.ts --> Writes files, updates manifest, injects source tracking
Phase 4: validate.ts --> Checks against agentskills.io spec (<500 lines, <5K tokens)
Phase 5: detect-sources.ts --> Records provenance (openskills/skills.sh/skillshare/git)
The agent provides the intelligence. The scripts handle file I/O, backup, validation, and source tracking.
Five compaction strategies, applied per-cluster:
| Strategy | When | Example |
|---|---|---|
| merge | 2+ skills with >30% content duplication | Two overlapping animation-audit skills → single unified skill |
| absorb | Small skill is a subset of a larger one | A 23-line router skill → becomes a reference file in the parent framework skill |
| extract-shared | Group shares boilerplate template | 6 skills sharing ~30% identical content → shared references/common.md |
| refactor | Single skill >300 lines, no references/ | 450-line monolith → concise body + reference files (progressive disclosure) |
| no-op | Already well-structured | Skill already uses references/ and is under limits → no changes |
Imagine 6 skills in the same domain that each include an identical assessment template, output format, and measurement framework — copy-pasted verbatim across all of them:
skill-a (382 lines) ─┐
skill-b (398 lines) │ Assessment template: identical
skill-c (371 lines) ├─ Output format: identical
skill-d (454 lines) │ Measurement framework: identical
skill-e (403 lines) │ Unique content: 60-70% each
skill-f (389 lines) ─┘
Strategy: extract-shared — Pull the shared content into a single references/shared-framework.md. Each skill references it instead of duplicating it.
Result: ~800 lines eliminated, ~7K tokens freed, zero information lost.
skill-compact detects how each skill was installed and can trigger updates before re-compacting:
| Manager | Detection method | Update command |
|---|---|---|
| openskills | ~/.openskills/registry.json |
npx openskills update |
| skills.sh | ~/.config/skills/manifest.json, symlinks |
npx skills update |
| skillshare | ~/.config/skillshare/skills/ symlinks |
skillshare update |
| git | .git in skills dir, git remote |
git pull |
| manual | Everything else | Manual reinstall |
The update-then-recompact workflow:
update-sources.tspulls fresh copies from upstream- Compares content hashes against the manifest to detect what changed
- Reports which compacted skills need to be re-run
- Agent re-applies the stored merge decisions from the manifest
All scripts output JSON and are run via npx tsx:
# Scan: inventory all skills
npx tsx scripts/scan.ts ~/.claude/skills
# Cluster: find overlapping groups
npx tsx scripts/group.ts ~/.claude/skills
# Backup: snapshot before changes
npx tsx scripts/backup.ts ~/.claude/skills
# Write: save compacted output (agent pipes content to stdin)
echo "$CONTENT" | npx tsx scripts/write-compact.ts <dir> <name> <strategy> '<sources>'
# Validate: check spec compliance
npx tsx scripts/validate.ts ~/.claude/skills
# Detect sources: record provenance
npx tsx scripts/detect-sources.ts ~/.claude/skills
# Update: pull upstream changes, report what's stale
npx tsx scripts/update-sources.ts ~/.claude/skills
# Restore: roll back from backup
npx tsx scripts/restore.ts ~/.claude/skills [backup-name]
# Manifest: view compaction history
npx tsx scripts/manifest.ts status ~/.claude/skills| Tool | What it does | What it doesn't do |
|---|---|---|
| openskills | Installs and syncs skills | No dedup, no merging, no compaction |
| skills.sh | Installs to 40+ agents, updates | No content analysis, no overlap detection |
| skillshare | Shares skills between projects | No semantic grouping, no compaction |
| skill-compact | Finds duplication, merges, validates, tracks sources | Doesn't install skills (use the above for that) |
They install. We optimize. They complement each other.
skill-compact/
├── SKILL.md # The skill (what agents read and follow)
├── references/
│ ├── best-practices.md # Compaction rules from agentskills.io spec + Anthropic guide
│ ├── strategies.md # Detailed process for each strategy
│ ├── spec-checklist.md # Validation checklist
│ └── prompts/
│ ├── analyze-cluster.md # Prompt template for cluster analysis
│ └── execute-compact.md # Prompt template for generating compacted output
├── scripts/
│ ├── scan.ts # Phase 1: Scan skills directory
│ ├── group.ts # Phase 2: Cluster by keyword similarity
│ ├── backup.ts # Phase 3: Timestamped backup
│ ├── write-compact.ts # Phase 3: Write compacted files + manifest
│ ├── validate.ts # Phase 4: Spec compliance validation
│ ├── detect-sources.ts # Phase 5: Detect skill sources
│ ├── update-sources.ts # Update from upstream, detect changes
│ ├── restore.ts # Restore from backup
│ └── manifest.ts # Read/write compaction manifest
└── src/
├── types.ts # TypeScript interfaces
└── parser.ts # SKILL.md parser + directory scanner
git clone https://github.com/JuanJoseGonGi/skill-compact.git
cd skill-compact
npm install
npm run build # Build with tsup
npm test # Run vitest (16 tests)
npm run lint # Type-check with tsc- Node.js 20+
tsx(included as dev dependency)