v3.11.0: one skill instead of six

The Claude Code plugin now registers one skill instead of six. Nothing was deleted, nothing was renamed, and every install command is unchanged.

What changed

The five language variants moved from skills/planning-with-files-<lang>/ to skills/i18n/planning-with-files-<lang>/. One directory of depth is the whole mechanism: Claude Code discovers a plugin's skills by scanning skills/*/SKILL.md at a single level and does not recurse, while npx skills add resolves --skill by skill name across a recursive scan and does not care about depth.

/plan-ar, /plan-de, /plan-es, /plan-zh and /plan-zht now read their translated skill from disk, and each one states that the status tokens stay literal English because check-complete.sh matches them with grep -F.

Measured, not inferred

Against the real Claude Code loader:

	before	after
Registered plugin skills	6	1
Components	19	14
Always-on tokens per session	~2,254	~1,042

All thirteen slash commands survive. The skills CLI still discovers all seven skills by name, and npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de installs to the same destination as before with the full 20-script surface and pulls in nothing else.

Also in this release

• docs/languages.md, the page the translations never had. docs/ carried a setup guide for every supported IDE and nothing for languages.
• Seven shell hooks could emit JSON with a raw control character on macOS. They interpolated a json.dumps result and emitted it with echo; under sh on macOS, where /bin/sh is bash in POSIX mode with xpg_echo, echo turns the escaped newline back into a real one. All seven now use printf '%s\n'.

Full suite 434 passed, 10 skipped, 497 subtests.

Known limitation

An existing variant install records the old path in its skills lock file, so npx skills update cannot resolve it until the skill is reinstalled. The installed skill keeps working and a fresh install always works. Nothing in this change could avoid that; it is inherent to moving a directory.

Thanks

This took four attempts across seven months of the issue tracker, so credit goes to everyone who pushed on it.

• @sean3808 opened #130 in April with the analysis that framed the whole problem: identical scripts and templates, prose the only real difference, and five skill descriptions loaded into every session that most users would never invoke. Every later attempt is a variation on that report.
• @dylanpulver wrote the answer that shipped (#226). He found the one-level plugin scan, checked the install route instead of assuming it, and carried the literal English status-token warning into all five commands where an earlier attempt had not. He also named the one cost he could not remove, which is what made the change reviewable, and diagnosed the macOS echo bug while rebasing.
• @SomSamantray audited the five variants against the canonical skill in #216 and proved the drift #130 predicted: twelve missing scripts, a missing Windows UTF-8 fix, and sync tooling covering only three dispatch targets. That shipped as v3.10.0 and had to land before this change was safe.
• @oaabahussain asked in #151 for a single canonical source with a CI parity gate. The gate shipped in v2.37.0 and is why this move could be verified rather than hoped at.
• @back1ply (#53) and @tiptinker (#47) filed the earliest two reports about the same duplication from the other direction, and are why scripts/sync-ide-folders.py exists.

Why this took so long

The obvious fix was to delete the five directories, and it was proposed more than once. It could not be taken. Skill listings on a public directory cannot be retracted once published, so deleting the folders would not have removed the entries. It would have left five permanent listings whose install command had started to fail, which is worse for the people using them than either keeping or removing them. The variants also have real users who chose them deliberately, and breaking a working install is not a reasonable price for a packaging problem.

What was needed was a route that changes nothing anyone depends on, and it took until #226 to find one. The delay was not doubt about whether the problem was real. It was refusing to fix it by breaking installs.