Dylan Pulver
5fddf55cda
The Claude Code plugin scan reads skills/*/SKILL.md and does not recurse, so each of the five language variants was registered for every plugin user and paid its description in every session's system prompt. Measured with claude plugin details on v3.10.1, that was about 1,010 of the plugin's roughly 2,254 always-on tokens. Moving the variants to skills/i18n/planning-with-files-<lang>/ takes them out of the plugin scan while keeping every skill name, every skill-route install command and every install destination unchanged: npx skills add resolves --skill by name over a recursive scan and still installs to ~/.claude/skills/planning-with-files-<lang>/. The five language slash commands can no longer invoke a plugin-registered skill by name, so they now read the translated SKILL.md from the skill-route path or the plugin marketplace path, which keeps the translated body and the translated templates in play. They also state that the status tokens stay literal English, since check-complete.sh matches them with grep -F.
3.6 KiB
Contributing
Thank you for considering a contribution to planning-with-files.
This project keeps contribution work small, traceable, and reviewable. Please make one logical change per pull request and keep the tone concise and concrete.
How to set up locally
Fork the repository, then clone your fork:
git clone https://github.com/YOUR-USERNAME/planning-with-files.git
cd planning-with-files
Add the upstream repository so you can sync your fork with the original project:
git remote add upstream https://github.com/OthmanAdi/planning-with-files.git
git fetch upstream
The canonical skill lives here:
skills/planning-with-files/SKILL.md
Before opening a pull request, run the test suite:
python -m pytest tests/ -q
Two pre-existing Windows exec-bit test failures may appear on Windows. If those are the only failures, note that in your pull request description.
Project layout
The canonical skill source is:
skills/planning-with-files/
Language variants live under directories that follow this pattern:
skills/i18n/planning-with-files-<lang>/
Keep them one directory below skills/. The Claude Code plugin scan reads skills/*/SKILL.md and does not recurse, so a variant placed directly under skills/ is registered for every plugin user and its description is added to every session's system prompt. tests/test_plugin_skill_surface.py fails if that happens.
IDE adapter variants live under these directories:
.codebuddy/
.codex/
.cursor/
.factory/
.hermes/
.mastracode/
.opencode/
.pi/
The clawhub-upload/ directory is gitignored and handled manually. Do not rely on it as the source of truth for repository changes.
Submitting a PR
Use a focused branch name that describes the type of change:
fix/short-description
feat/short-description
docs/short-description
Use Conventional Commits for commit messages:
fix: describe the bug fix
feat: describe the new behavior
docs: describe the documentation change
Keep each pull request to one logical change. A documentation fix, a language variant update, and a test change should usually be separate pull requests.
When opening the pull request, include:
- What changed
- Why it changed
- How you tested it
- Any known limitations or platform-specific notes
If the pull request closes an issue, include the issue reference in the description:
Closes #123
Authorship and credit
The project maintains contributor credit in CONTRIBUTORS.md.
Merged pull requests earn a permanent contributor entry. Keep your Git author information accurate because your commits remain part of the project history and are not treated as disposable metadata.
Small contributions count. Documentation fixes, language variant updates, tests, and adapter improvements all help maintain the project.
Language variant contributions
Translations and language variant improvements are welcome.
When working on a language variant, compare it against the canonical skill in:
skills/planning-with-files/SKILL.md
Keep translated variants in parity with the canonical version. Do not ship a localized description with an English body stub. If a section cannot be translated yet, leave a clear note in the pull request instead of hiding incomplete work in the file.
Where to ask questions
For general questions, use GitHub Discussions.
For issue-specific questions, comment on the relevant issue. If maintainer attention is needed, tag @OthmanAdi and describe the specific point you need help with.
Good questions include context, what you tried, and where you are blocked.