feat: add /upkeep:trim skill for unused dependency weight - #23
Merged
Conversation
Adds a fourth skill answering the question the existing three do not: what is in the dependency tree that we do not use, and what does it cost. /upkeep:deps answers "what is outdated," /upkeep:audit answers "what is vulnerable" -- neither surfaces a dependency that is current, has no advisories, and is still dead weight. Motivating case: libsql-search ships a text-embedding library that transitively installs sharp + libvips (~15.6 MB of native binaries) because @huggingface/transformers declares sharp as a hard dependency, even though nothing in the project's source touches it. The skill is the entry point and procedure; heavy per-package investigation delegates to the js-dep-analyst agent (llbbl/claude-agents) so the caller gets a verdict back instead of tree/manifest/registry dumps. No new CLI commands -- upkeep detect, upkeep imports, and upkeep audit already cover the CLI-side steps. Encodes several heuristics from the motivating investigation: the package manager doesn't change the dependency graph, "not built" isn't "not installed," a caret range can strand a fix behind an intermediate package's range (making override cheaper than removal), a baseline comment isn't a diagnosis, check upstream before designing a local workaround, and "no good lever exists today" is a legitimate outcome. Also registers the skill in README.md (skill list, repo-structure tree, "all four skills") and .claude-plugin/marketplace.json (plugin description).
This PR adds skills/trim/SKILL.md, which carries a version: frontmatter field, but the version tooling hardcoded the skill list rather than globbing it — update-all-versions, set-version, and show-versions each named only deps/audit/quality. Left as-is, the trim skill would have stayed pinned at 0.4.3 while every other version-bearing file moved on, the same drift class as the .claude-plugin/marketplace.json bug fixed in #14. Adds trim to all three recipes and to the version-bearing file list in docs/RELEASING.md. Note the git add lines in commit-version and the auto-release workflow already use the skills/*/SKILL.md glob, so staging was never the gap — only the sed lines that write the version were. Verified: deliberately set the trim skill to version 9.9.9, ran just version-sync, and confirmed it was corrected back to 0.4.3; just show-versions now lists all eight version-bearing files in agreement; just lint clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/upkeep:trim, answering what the existing three don't: what's in the dependency tree that we don't use, and what does it costWhy
/upkeep:depsanswers "what is outdated."/upkeep:auditanswers "what is vulnerable." Neither surfaces a dependency that is perfectly current, carries no advisories, and is still pure dead weight.Motivating case:
libsql-searchships a text-embedding library that transitively installssharp+libvips(~15.6 MB of native binaries) because@huggingface/transformersdeclaressharpas a harddependenciesentry. Nothing in that project's source touches it.depswould not flag it (not outdated), andauditonly reported the advisories it dragged along -- which had been baselined and stopped being read.Design
The skill is the entry point and procedure; heavy per-package investigation delegates to the
js-dep-analystagent. Dependency investigation is read-heavy -- trees, parent manifests, registry lookups -- so the caller should get the verdict back rather than the dumps.No new CLI commands.
upkeep detect,upkeep imports <pkg>(AST usage analysis), andupkeep auditalready cover the CLI-side steps, consistent with the existing guidance to only add binary support when native tooling output is hard to consume or needs cross-tool normalization.Heuristics the skill encodes
Each of these was a real mistake or discovery from the motivating investigation:
Validation
just lintjust test(405 pass / 15 skip / 0 fail).claude-plugin/marketplace.jsonvalidated as JSONCloses #22