juanjosegongi/maintaining-skills

Maintaining Skills

Three modes for managing your agent skills lifecycle.

When to use

• refresh — pulling upstream changes, identifying skills that no longer match recent transcripts, discovering missing skills you might want
• compact — deduplicating overlapping skills, restructuring monolithic SKILL.md files, validating against the agentskills.io spec
• curate — auditing authors and provenance, separating user-authored from external skills, checking the skill listing budget against the 1% context window limit

Picking the mode

| You want to… | Mode | |--------------|------| | Sync with upstream catalogs | refresh | | Find skills that haven't been used in 60 days | refresh | | Discover skills you don't have yet | refresh | | Merge near-duplicate skills | compact | | Move oversized SKILL.md content into references/ | compact | | Validate against the agentskills.io spec | compact | | Decide which skills should be global vs per-project | curate | | Identify which skills you authored vs imported | curate | | Diagnose the "skills > 1% of context" warning | curate |

Workflows

• references/refresh.md — daily/weekly transcript-driven refresh
• references/compact.md — scan → cluster → strategy → write → validate
• references/curate.md — author audit, budget check, scope decisions

Prerequisites

npm install              # in maintaining-skills/
npm install -g tsx       # if not present
bun install -g https://github.com/tobi/qmd   # required only for refresh mode

Quick reference

# Refresh
npm run refresh:daily
npm run refresh:weekly

# Compact
npm run compact:scan -- ~/.claude/skills
npm run compact:group -- ~/.claude/skills
npm run compact:validate -- ~/.claude/skills

# Curate
npm run curate:authors -- ~/dev/skills
npm run curate:budget -- ~/.claude/skills

Each mode is independent — start with the workflow page that matches your task. Don't run all three in one pass; the work units are different.