Skip to content

fix(converter): de-duplicate skill descriptions in command wrappers#28

Merged
ak2k merged 1 commit into
mainfrom
worktree-skills-dedup
May 20, 2026
Merged

fix(converter): de-duplicate skill descriptions in command wrappers#28
ak2k merged 1 commit into
mainfrom
worktree-skills-dedup

Conversation

@ak2k

@ak2k ak2k commented May 20, 2026

Copy link
Copy Markdown
Owner

Summary

Each skill was showing up twice in interactive Claude Code's /context skills list:

├ ce-compound-refresh: ~170 tokens          ← SKILL.md description
├ ce-lite:ce-compound-refresh: ~60 tokens   ← commands/<name>.md description

For ce-lite's 88 command wrappers, that's ~6k tokens of duplicated description text.

Root cause

generate_commands.py was emitting a shortened SKILL.md description: into every commands/<name>.md frontmatter. Claude Code counts each as a separate skill entry: bare-named for SKILL.md, plugin-namespaced for the command wrapper.

Fix

Command-wrapper description: is now just the skill name itself (description: "ce-plan" instead of description: "Create structured plans..."). Satisfies validate.py's non-empty-description check while collapsing each duplicate entry to ~5 tokens.

The SKILL.md description is still the canonical routing signal. The command wrapper exists only for /<plugin>:<name> dispatch reliability (see generate_commands.py module docstring for why command wrappers exist at all).

shorten_description + MAX_DESCRIPTION_LEN are dropped — no longer used.

How this was discovered

Measured interactively in #27's A/B run. The +7.9k ce-lite-side skills bump (ce-lite 12.5k vs upstream 4.6k) was the smoking gun — 88 skills vs upstream's 29 explained part of it, but the +60-token-per-command duplication explained the rest.

Expected impact

After merge + publish-dist regen:

  • ce-lite Skills slot: 12.5k → ~6.5k
  • Total savings vs upstream: −105.2k → ~−111k

PR #27's README A/B table will need a refresh in a follow-up.

Test plan

  • nix flake check green (treefmt + actionlint + 161 pytest)
  • Re-ran full pipeline locally against pinned upstream tag; validate.py --upstream byte-equivalent round-trip still passes
  • After merge, trigger publish-dist and re-measure with isolated CLAUDE_CONFIG_DIRs

Each skill was showing up twice in Claude Code's interactive `/context`
skills list:

  ├ ce-compound-refresh: ~170 tokens          ← SKILL.md description
  ├ ce-lite:ce-compound-refresh: ~60 tokens   ← commands/<name>.md description

generate_commands.py was carrying a shortened SKILL.md description in
every command wrapper's frontmatter. Claude Code counted both — once as
a bare-named skill (from SKILL.md), once as a plugin-namespaced command
(from commands/<name>.md). For ce-lite's 88 commands, ~6k tokens of
duplicated description blurb.

Fix: command-wrapper `description:` is now just the skill name itself.
Satisfies validate.py's non-empty-description check while collapsing
each duplicate entry to ~5 tokens (the bare skill name in the autocomplete
namespace). The SKILL.md description is still the canonical routing
signal; the command wrapper exists only for `/<plugin>:<name>` dispatch
reliability (see generate_commands.py module docstring).

Drops `shorten_description` and `MAX_DESCRIPTION_LEN` — no longer used.

Tests updated.

After merge, trigger publish-dist to regenerate dist/ and re-measure
against the README's A/B table. Expected: ce-lite skills slot drops
~12.5k → ~6.5k, total savings vs upstream grows from −105.2k → ~−111k.
@ak2k ak2k merged commit 8b8bbb0 into main May 20, 2026
2 checks passed
@ak2k ak2k deleted the worktree-skills-dedup branch May 20, 2026 23:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant