Compare commits

...
3 Commits
Author SHA1 Message Date
OthmanAdi 9e94390e59 release: v3.11.2 2026-08-22 13:03:16 +02:00
OthmanAdi 71258dae71 fix: create the skill destination before manual copies 2026-08-22 12:53:05 +02:00
Dylan Pulver 3c5ea2b14f docs: name the skill directory in the skills-only install commands
docs/installation.md:101 and docs/windows.md:38 copy skills/* into the user's
skills directory. Since the v3.11.0 move of the language variants to
skills/i18n/, that glob also copies i18n/, which is not a skill: the user ends
up with ~/.claude/skills/i18n/ holding no SKILL.md, and the five translations
at ~/.claude/skills/i18n/planning-with-files-<lang>/ rather than the
~/.claude/skills/planning-with-files-<lang>/ that commands/plan-<lang>.md
probes first.

Both now name skills/planning-with-files, matching section 4 of
installation.md, README.md:250 and every other copy command in docs/. A second
line copying skills/i18n/* would restore what the glob used to install, but
docs/languages.md:26 states that installing English installs no translation,
and six skills in ~/.claude/skills/ returns the five extra descriptions to
every session that PR #226 removed from the plugin route.

The guard lives in tests/test_plugin_skill_surface.py, which owns the skills/
depth invariant. It matches only lines starting with cp or Copy-Item, so the
prose describing the skills/*/SKILL.md plugin scan does not trip it.
2026-08-22 12:53:05 +02:00
24 changed files with 125 additions and 23 deletions
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
# Planning with Files
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans that survive context loss, /clear, and crashes, with an opt-in completion gate and multi-agent shared state on disk. Manus-style, installs across 60+ agents via the SKILL.md standard.",
"version": "3.11.1"
"version": "3.11.2"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.11.1",
"version": "3.11.2",
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/inject-plan.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
# Planning with Files
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes."
metadata:
version: "3.11.1"
version: "3.11.2"
---
> Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.11.1",
"version": "3.11.2",
"description": "Persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md and progress.md on disk so the plan survives /clear, context loss and compaction. Manus-style. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
+18
View File
@@ -2,6 +2,24 @@
All notable changes to this project will be documented in this file.
## [3.11.2] - 2026-08-22
### Fixed
- **The two manual skills-only install commands copied the whole `skills/` directory after the language variants moved under `skills/i18n/` (PR #229 by @dylanpulver).** The Unix and PowerShell instructions now copy only `skills/planning-with-files`, so an English install no longer creates an unusable `~/.claude/skills/i18n/` entry or places the five translations one directory below the paths their commands probe.
- **A fresh manual install could flatten the canonical skill into `~/.claude/skills/`.** With one source directory and no existing destination, `cp` and `Copy-Item` can create the destination from the source contents, leaving `SKILL.md` directly under `skills/`. Both instructions now create `~/.claude/skills` before copying the canonical skill directory into it.
### Changed
- `tests/test_plugin_skill_surface.py` now scans tracked Markdown for `cp` or `Copy-Item` commands that copy `skills/*` wholesale. It also locks the destination-creation step before both manual copies and falls back to a filesystem scan when Git is unavailable.
### Verification
- Required baseline before integration: 434 passed, 10 skipped, and 497 subtests passed.
- Exact contributor head before the maintainer hardening: 435 passed, 10 skipped, and 497 subtests passed.
- Amended release candidate: 436 passed, 10 skipped, and 499 subtests passed. GitHub Actions passed on Ubuntu, macOS, and Windows, and the Pi extension Vitest job passed.
- `sync-ide-folders.py --verify` reports every maintained mirror in sync. `bump-version.py 3.11.2 --dry-run` resolves all 19 present parity targets with zero errors.
### Thanks
- Dylan traced the regression to the v3.11.0 language-directory move, found the only two whole-directory copy commands in tracked documentation, and added the guard that keeps that install shape out of future docs (PR #229).
## [3.11.1] - 2026-08-21
### Fixed
+2 -2
View File
@@ -7,8 +7,8 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.11.1"
date-released: "2026-08-14"
version: "3.11.2"
date-released: "2026-08-22"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
repository-code: "https://github.com/OthmanAdi/planning-with-files"
+2 -2
View File
@@ -374,7 +374,7 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
- [@Whxuan0701](https://github.com/Whxuan0701) (WeiHaoxuan) - [PR #223](https://github.com/OthmanAdi/planning-with-files/pull/223), [PR #222](https://github.com/OthmanAdi/planning-with-files/pull/222), [PR #224](https://github.com/OthmanAdi/planning-with-files/pull/224) (found that the `PLANNING_DISABLED=1` opt-out from #195 had never reached any of the ten GitHub Copilot hook entry points, that the #191 zero-phase guard was missing from the Copilot PowerShell stop hook, and that the Hermes determinism probe hardcoded `python` so it could not run where only `python3` exists; three single-commit PRs, each with a test that executes the real script. Auditing them surfaced three further defects fixed in the same release: the Cursor route had the same opt-out gap across all eight of its hooks, the disabled `PreToolUse` branch was widening Copilot's permissions rather than staying neutral, and `error-occurred.ps1` had never logged an error on Windows because it read stdin into PowerShell's automatic `$input` variable)
- [@dylanpulver](https://github.com/dylanpulver) (Dylan Pulver) - [PR #226](https://github.com/OthmanAdi/planning-with-files/pull/226) (answered issue #130 after two earlier attempts could not be taken: moved the five language variants one directory deeper so the Claude Code plugin scan, which reads `skills/*/SKILL.md` without recursing, stops registering them, while every `npx skills add --skill` command keeps resolving because that resolver matches by skill name across a recursive scan. Cut the plugin's always-on cost by roughly half without deleting, renaming or breaking a single install. Verified the install route rather than assuming it, carried the literal English status-token warning into all five language commands where an earlier attempt had not, and named the one cost he could not remove), [PR #228](https://github.com/OthmanAdi/planning-with-files/pull/228) (fixed the Copilot error hook, which fed its Python helpers with bash here-strings that dash cannot parse, so master CI had failed on the ubuntu leg for five consecutive runs. Reproduced the ubuntu condition locally instead of working from the log, and confirmed the suite genuinely exercises the path by reverting his own change. Declined the fix that would have looked right: copying the four sibling hooks' `echo` form clears the syntax error but silently corrupts JSON under dash, and he wrote that into the pull request rather than leaving it for review)
- [@dylanpulver](https://github.com/dylanpulver) (Dylan Pulver) - [PR #226](https://github.com/OthmanAdi/planning-with-files/pull/226) (answered issue #130 after two earlier attempts could not be taken: moved the five language variants one directory deeper so the Claude Code plugin scan, which reads `skills/*/SKILL.md` without recursing, stops registering them, while every `npx skills add --skill` command keeps resolving because that resolver matches by skill name across a recursive scan. Cut the plugin's always-on cost by roughly half without deleting, renaming or breaking a single install. Verified the install route rather than assuming it, carried the literal English status-token warning into all five language commands where an earlier attempt had not, and named the one cost he could not remove), [PR #228](https://github.com/OthmanAdi/planning-with-files/pull/228) (fixed the Copilot error hook, which fed its Python helpers with bash here-strings that dash cannot parse, so master CI had failed on the ubuntu leg for five consecutive runs. Reproduced the ubuntu condition locally instead of working from the log, and confirmed the suite genuinely exercises the path by reverting his own change. Declined the fix that would have looked right: copying the four sibling hooks' `echo` form clears the syntax error but silently corrupts JSON under dash, and he wrote that into the pull request rather than leaving it for review), [PR #229](https://github.com/OthmanAdi/planning-with-files/pull/229) (found the two manual install commands still copying `skills/*` after the translations moved under `skills/i18n/`, corrected both to name the canonical skill, and added a tracked-Markdown guard against the old install shape)
- [@sean3808](https://github.com/sean3808) (Sean) - [Issue #130](https://github.com/OthmanAdi/planning-with-files/issues/130) (opened the consolidation report in April 2026 with the analysis that framed the problem for every later attempt: identical scripts and templates, prose the only real difference, and five skill descriptions injected into every session that most users would never invoke; resolved in v3.11.0)
And many others who have starred, forked, and shared this project!
@@ -405,4 +405,4 @@ If you've contributed and don't see your name here, please open an issue! We wan
**Total Contributors:** 54+ and growing!
*Last updated: August 20, 2026*
*Last updated: August 22, 2026*
+1
View File
@@ -552,6 +552,7 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.11.2** | **Skills-only manual installs now copy one skill at the documented depth** (PR #229 by @dylanpulver). The Unix and PowerShell commands name `skills/planning-with-files` instead of copying `skills/*`, so the `skills/i18n/` subtree no longer lands below the loader path. Both instructions create `~/.claude/skills` first, which keeps a fresh install from placing `SKILL.md` directly under `skills/`. A tracked-Markdown test rejects the old whole-directory copy shape and locks the destination-creation step. |
| **v3.11.1** | **The Copilot error hook could not be parsed by a POSIX shell** (PR #228 by @dylanpulver). `error-occurred.sh` fed its two Python helpers with `<<<`, a bash here-string that dash does not implement, and the suite invokes the shell hooks as `sh script`, so the `#!/bin/bash` shebang never applied. On ubuntu runners the file died at line 32 with `Syntax error: redirection unexpected`, and master CI had failed on that leg for five consecutive runs. Both call sites now pipe with `printf '%s\n'`. The sibling `echo` form was deliberately not copied: dash expands backslash escapes, which would have traded a loud syntax error for silent JSON corruption. No user was affected, because Copilot invokes the hook under a `bash` key that bypasses the shebang. |
| **v3.11.0** | **The plugin registers one skill instead of six** (closes #130, reported by @sean3808; implemented by @dylanpulver in PR #226). The five language variants moved from `skills/planning-with-files-<lang>/` to `skills/i18n/planning-with-files-<lang>/`. Nothing deleted, nothing renamed, every `npx skills add --skill` command unchanged: Claude Code scans `skills/*/SKILL.md` one level without recursing, while the skills CLI resolves `--skill` by name across a recursive scan. Measured against the real loader, not inferred: 6 registered skills to 1, 19 components to 14, always-on cost roughly 2,254 to 1,042 tokens per session, with all thirteen slash commands intact. `/plan-de` and its four siblings read their translated skill from disk and state that the status tokens stay literal English, because `check-complete.sh` matches them with `grep -F`. Also fixes seven shell hooks that could emit JSON with a raw control character when run under a POSIX-mode shell on macOS. |
| **v3.10.2** | **`PLANNING_DISABLED=1` had never reached the GitHub Copilot or Cursor hooks** (PRs #223, #222 and #224, by @Whxuan0701). Both routes read `task_plan.md` directly instead of dispatching to the script that carries the #195 guard, so eighteen hook entry points ignored the opt-out entirely: a one-shot task sharing a working directory with an unrelated plan had no way to detach from it. Auditing the merge found three more: the disabled `PreToolUse` branch answered `permissionDecision: allow`, so turning the skill off widened Copilot's permissions instead of staying neutral; `.cursor/hooks/stop.ps1` was the last copy the #191 zero-phase guard never reached, still auto-continuing on `0/0 phases done`; and `error-occurred.ps1` had never logged an error on Windows because it read stdin into `$input`, PowerShell's automatic pipeline variable, which does not hold the assignment under `-File`. The opt-out tests now run every hook with the variable unset as well as set, because the disabled-only versions stayed green against a fleet gutted to emit `{}`. Suite 424 to 430. |
+2 -1
View File
@@ -98,7 +98,8 @@ If you only want the skill without the full plugin structure:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/skills/* ~/.claude/skills/
mkdir -p ~/.claude/skills
cp -r planning-with-files/skills/planning-with-files ~/.claude/skills/
```
---
+2 -1
View File
@@ -35,7 +35,8 @@ git clone https://github.com/OthmanAdi/planning-with-files.git $env:USERPROFILE\
```powershell
git clone https://github.com/OthmanAdi/planning-with-files.git
Copy-Item -Recurse planning-with-files\skills\* $env:USERPROFILE\.claude\skills\
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse planning-with-files\skills\planning-with-files $env:USERPROFILE\.claude\skills\
```
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
# نظام تخطيط الملفات
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
# Dateiplanungssystem
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
# Sistema de Planificación con Archivos
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-zh/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.11.1"
version: "3.11.2"
---
# Planning with Files
+81
View File
@@ -14,9 +14,16 @@ a recursive scan of the repository, and still installs to
This test fails if a variant is moved (or a new one is added) directly under
`skills/`, which would silently put those descriptions back into every session.
The extra depth also invalidated any install that copies `skills/*` wholesale
into a skills directory: `i18n/` is not a skill, and the five variants land a
level below where the loader and the `/plan-<lang>` commands look for them.
The last check below keeps that shape out of the shipped install docs.
"""
from __future__ import annotations
import re
import subprocess
import unittest
from pathlib import Path
@@ -34,11 +41,50 @@ EXPECTED_VARIANTS = {
}
# A copy command whose source is the whole skills/ directory. Prose that
# mentions `skills/*/SKILL.md` (the plugin scan) must not match, so the line
# has to start with the copy verb and the glob has to end the path segment.
WHOLESALE_COPY_RE = re.compile(r"^\s*(?:cp\s|Copy-Item\b).*skills[\\/]\*(?:\s|$)")
MANUAL_SKILL_COPY_COMMANDS = {
"docs/installation.md": (
"mkdir -p ~/.claude/skills",
"cp -r planning-with-files/skills/planning-with-files ~/.claude/skills/",
),
"docs/windows.md": (
r'New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills" | Out-Null',
r"Copy-Item -Recurse planning-with-files\skills\planning-with-files",
),
}
def _plugin_registered_skills():
"""Directory names the Claude Code plugin scan registers (skills/*/SKILL.md)."""
return {d.name for d in SKILLS_DIR.iterdir() if (d / "SKILL.md").is_file()}
def _tracked_markdown():
"""Every tracked .md file, via git; glob fallback for non-git checkouts."""
try:
proc = subprocess.run(
["git", "-c", "core.quotepath=off", "ls-files", "--", "*.md"],
cwd=str(REPO_ROOT),
text=True,
encoding="utf-8",
capture_output=True,
check=False,
)
if proc.returncode == 0 and proc.stdout.strip():
return [REPO_ROOT / line for line in proc.stdout.splitlines() if line]
except OSError:
pass
return [
p
for p in REPO_ROOT.rglob("*.md")
if ".git" not in p.parts and "node_modules" not in p.parts
]
class PluginSkillSurfaceTests(unittest.TestCase):
def test_plugin_registers_canonical_skill_only(self):
self.assertEqual(
@@ -61,6 +107,41 @@ class PluginSkillSurfaceTests(unittest.TestCase):
text = (I18N_DIR / name / "SKILL.md").read_text(encoding="utf-8")
self.assertIn(f"\nname: {name}\n", text)
def test_no_doc_installs_by_copying_the_skills_directory(self):
docs = _tracked_markdown()
self.assertTrue(docs, "no tracked .md files discovered")
offenders = []
for doc in docs:
if not doc.is_file():
continue
for lineno, line in enumerate(
doc.read_text(encoding="utf-8").splitlines(), start=1
):
if WHOLESALE_COPY_RE.match(line):
rel = doc.relative_to(REPO_ROOT).as_posix()
offenders.append(f"{rel}:{lineno}: {line.strip()}")
self.assertFalse(
offenders,
"install command copies the whole skills/ directory, which since "
"v3.11.0 also copies i18n/ (not a skill) and puts the five "
"variants a level below where the loader and the /plan-<lang> "
"commands look; name skills/planning-with-files instead: "
+ "; ".join(offenders),
)
def test_manual_skill_copies_create_destination_first(self):
for rel, (create_destination, copy_skill) in MANUAL_SKILL_COPY_COMMANDS.items():
with self.subTest(doc=rel):
text = (REPO_ROOT / rel).read_text(encoding="utf-8")
self.assertIn(create_destination, text)
self.assertIn(copy_skill, text)
self.assertLess(
text.index(create_destination),
text.index(copy_skill),
"the skills directory must exist before the canonical skill "
"directory is copied into it",
)
if __name__ == "__main__":
unittest.main()