diff --git a/docs/en/skills.md b/docs/en/skills.md index bffe8c0..85e4839 100644 --- a/docs/en/skills.md +++ b/docs/en/skills.md @@ -16,7 +16,7 @@ Each bundled skill is shown as its own block: name, status, install locations, a - `installed` — a matching copy is present in at least one inspected location - `outdated` — a copy exists but differs from the bundled skill, or the path exists without `SKILL.md` -- `missing` — no copy was found +- `missing` — no copy was found in the inspected locations `--target` accepts a comma-separated list of `agents`, `claude`, `cursor`, and `codex`. `--user` and `--project` limit the scan to user-level or project-local directories. Without those flags, `list` inspects both scopes. @@ -44,6 +44,28 @@ pt-snap skill uninstall --dir C:\Users\you\custom-skills ## Install skills +### Custom-directory availability and helper handoff + +After `pt-snap skill install --dir '' --json`, verify that same +directory with `pt-snap skill list --dir '' --json`. Pass the parent +containing the skill folders. The default `pt-snap skill list --json` checks +only built-in host locations and may still say `missing`; custom directories +are not registered automatically. JSON `locations` identifies the checked paths. + +On-disk status and host loading are separate. An `installed` copy is not proof +that the host discovers the custom directory or has loaded the skill. A readable +JSON `source_dir` is the source catalog, not proof of either installation or +loading. `pt-snap-helper` may hand off to an already loaded skill (or one loaded +successfully through the host's supported loader) despite default `missing`, +without a redundant install. If loading is unavailable, it pauses the diagnostic +handoff and asks the user to configure host discovery and restart. If the active +copy is known to be outdated, upgrade and restart before diagnosis. Missing or +outdated copies in the intended custom location require an install or upgrade +with the same `--dir`; the helper only explains these commands, never runs them. +It reports inspected status and host-loading evidence separately. + +### Install commands + ```bash pt-snap skill install pt-snap skill install pt-snap-setup --target claude diff --git a/docs/zh/skills.md b/docs/zh/skills.md index 7def3ff..92acc59 100644 --- a/docs/zh/skills.md +++ b/docs/zh/skills.md @@ -16,7 +16,7 @@ pt-snap skill list --target claude --user - `installed` — 至少一个检查位置存在内容匹配的副本 - `outdated` — 已有副本但与随包版本不同,或路径存在但没有 `SKILL.md` -- `missing` — 未找到副本 +- `missing` — 在本次检查的位置未找到副本 `--target` 接受逗号分隔的 `agents`、`claude`、`cursor`、`codex`。`--user` 和 `--project` 分别只检查用户级或当前项目目录。不传这些选项时,`list` 会同时检查两个范围。 @@ -44,6 +44,24 @@ pt-snap skill uninstall --dir C:\Users\you\custom-skills ## 安装 skill +### 自定义目录可用性与 helper 交接 + +执行 `pt-snap skill install --dir '' --json` 后,用 +`pt-snap skill list --dir '' --json` 复查同一目录,传入包含各 skill +子目录的父目录。默认的 `pt-snap skill list --json` 只检查内置宿主位置,仍可能 +显示 `missing`;自定义目录不会自动登记。JSON 的 `locations` 列出实际检查路径。 + +磁盘状态与宿主加载状态是两回事。`installed` 不代表宿主能发现该自定义目录或已经 +加载 skill;JSON 中可读的 `source_dir` 是目录源,也不能证明安装或加载成功。 +如果所需 skill 已被宿主加载(或通过宿主支持的加载器成功加载),即使默认列表 +显示 `missing`,`pt-snap-helper` 也可直接交接,无需重复安装。如果宿主无法加载, +helper 会暂停诊断交接,请用户配置宿主发现目录并重启。如果已知当前使用的副本 +过期,应先升级并重启,再进行诊断。若预期的自定义位置确实为 `missing` 或 +`outdated`,安装或升级时应保留同一个 `--dir`;helper 只说明命令,不执行。 +交接时会分别报告检查位置的状态和宿主加载证据。 + +### 安装命令 + ```bash pt-snap skill install pt-snap skill install pt-snap-setup --target claude diff --git a/skills/pt-snap-helper/SKILL.md b/skills/pt-snap-helper/SKILL.md index 865d4a6..6787552 100644 --- a/skills/pt-snap-helper/SKILL.md +++ b/skills/pt-snap-helper/SKILL.md @@ -35,8 +35,46 @@ or `missing`. If `pt-snap` is missing, stop routing diagnostics and hand off to `pt-snap-setup`. Do not install the Python package from this skill. -If a needed skill is `missing` or `outdated`, tell the user how to install or -upgrade it. Do not run install or upgrade from this skill. +### Interpret availability in the inspected scope + +`missing` means no copy was found in the inspected locations, not that the +skill is unavailable to the current host. The default list checks built-in +host directories in user and project scopes; custom install directories are +not registered automatically. Inspect `skills[].locations` for each path and +status rather than assuming the summary describes the host's active copy. +A readable `source_dir` is catalog content, not proof of installation or host +loading. Do not relabel a CLI status based on source readability. + +If the user installed with `--dir`, recheck the same skills directory (the +parent containing `/SKILL.md`, not the individual skill folder): + +```bash +pt-snap skill list --dir '' --json +``` + +Use the known install destination or ask the user for it; do not guess or scan +unrelated directories. Do not combine `--dir` with `--target`, `--user`, or +`--project`. A custom-directory `installed` result verifies the on-disk copy; +it does not establish that the host discovers that directory or has loaded it. + +### Decide the handoff using host-loading evidence + +- If the active copy is known to be outdated, request an upgrade and restart + before diagnostic handoff. An outdated copy in another inspected location + does not establish that the active copy is outdated. +- If the host has already loaded the needed skill, hand off to it even when + the default list says `missing`. Otherwise, use the host's supported skill + loader when it exposes that exact skill and hand off after loading succeeds. + Do not require a redundant install just to change the default list status. +- If the host cannot load the skill, pause the diagnostic handoff. For a custom + directory with an `installed` copy, ask the user to make that directory + discoverable through the host's supported configuration and restart; do not + recommend reinstalling an identical copy. If the intended location is truly + `missing` or `outdated`, explain the corresponding install or upgrade command + for that location. Do not run install or upgrade from this skill. +- Report the inspected directory/scope, its status, and host-loading evidence + separately in the handoff. If loading is unverified, say so and give the next + action; never substitute this helper's own diagnostic analysis. Install or upgrade examples the user can run after they confirm they want the skills installed or updated. Do not run these commands from this skill: @@ -48,6 +86,13 @@ pt-snap skill upgrade pt-snap-helper --json pt-snap skill upgrade --json ``` +For a custom destination, preserve the same directory and needed skill name: + +```bash +pt-snap skill install --dir '' --json +pt-snap skill upgrade --dir '' --json +``` + After any install, upgrade, or uninstall that changes skill files, the host agent must be restarted before the change is visible: diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md index 865d4a6..6787552 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md @@ -35,8 +35,46 @@ or `missing`. If `pt-snap` is missing, stop routing diagnostics and hand off to `pt-snap-setup`. Do not install the Python package from this skill. -If a needed skill is `missing` or `outdated`, tell the user how to install or -upgrade it. Do not run install or upgrade from this skill. +### Interpret availability in the inspected scope + +`missing` means no copy was found in the inspected locations, not that the +skill is unavailable to the current host. The default list checks built-in +host directories in user and project scopes; custom install directories are +not registered automatically. Inspect `skills[].locations` for each path and +status rather than assuming the summary describes the host's active copy. +A readable `source_dir` is catalog content, not proof of installation or host +loading. Do not relabel a CLI status based on source readability. + +If the user installed with `--dir`, recheck the same skills directory (the +parent containing `/SKILL.md`, not the individual skill folder): + +```bash +pt-snap skill list --dir '' --json +``` + +Use the known install destination or ask the user for it; do not guess or scan +unrelated directories. Do not combine `--dir` with `--target`, `--user`, or +`--project`. A custom-directory `installed` result verifies the on-disk copy; +it does not establish that the host discovers that directory or has loaded it. + +### Decide the handoff using host-loading evidence + +- If the active copy is known to be outdated, request an upgrade and restart + before diagnostic handoff. An outdated copy in another inspected location + does not establish that the active copy is outdated. +- If the host has already loaded the needed skill, hand off to it even when + the default list says `missing`. Otherwise, use the host's supported skill + loader when it exposes that exact skill and hand off after loading succeeds. + Do not require a redundant install just to change the default list status. +- If the host cannot load the skill, pause the diagnostic handoff. For a custom + directory with an `installed` copy, ask the user to make that directory + discoverable through the host's supported configuration and restart; do not + recommend reinstalling an identical copy. If the intended location is truly + `missing` or `outdated`, explain the corresponding install or upgrade command + for that location. Do not run install or upgrade from this skill. +- Report the inspected directory/scope, its status, and host-loading evidence + separately in the handoff. If loading is unverified, say so and give the next + action; never substitute this helper's own diagnostic analysis. Install or upgrade examples the user can run after they confirm they want the skills installed or updated. Do not run these commands from this skill: @@ -48,6 +86,13 @@ pt-snap skill upgrade pt-snap-helper --json pt-snap skill upgrade --json ``` +For a custom destination, preserve the same directory and needed skill name: + +```bash +pt-snap skill install --dir '' --json +pt-snap skill upgrade --dir '' --json +``` + After any install, upgrade, or uninstall that changes skill files, the host agent must be restarted before the change is visible: diff --git a/tests/skills/test_helper_availability.py b/tests/skills/test_helper_availability.py new file mode 100644 index 0000000..f34218e --- /dev/null +++ b/tests/skills/test_helper_availability.py @@ -0,0 +1,84 @@ +"""Availability instructions and the real CLI evidence used by the helper.""" + +import json +from pathlib import Path + +import pytest +from typer.testing import CliRunner + +from pt_snap_cli.cli import app + +REPO_ROOT = Path(__file__).resolve().parents[2] + + +@pytest.mark.parametrize( + "required_rule", + [ + "`missing` means no copy was found in the inspected locations", + "pt-snap skill list --dir '' --json", + "A readable `source_dir` is catalog content, not proof of installation or host loading", + "If the host has already loaded the needed skill, hand off to it even when the default list says `missing`", + "If the host cannot load the skill, pause the diagnostic handoff", + "If the active copy is known to be outdated, request an upgrade and restart before diagnostic handoff", + "Report the inspected directory/scope, its status, and host-loading evidence separately", + ], +) +def test_helper_availability_decision_rules(required_rule: str) -> None: + skill = (REPO_ROOT / "skills/pt-snap-helper/SKILL.md").read_text(encoding="utf-8") + availability = skill.split("## Prerequisite: check skill availability", 1)[1].split( + "## Prefer `--json` where supported", 1 + )[0] + assert required_rule in " ".join(availability.split()) + + +@pytest.mark.parametrize("custom_status", ["installed", "outdated", "missing"]) +def test_custom_install_status_is_scoped_to_inspected_directory( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, custom_status: str +) -> None: + # Keep both default scopes and host overrides away from developer directories. + home = tmp_path / "home" + project = tmp_path / "project" + home.mkdir() + project.mkdir() + monkeypatch.setattr(Path, "home", lambda: home) + monkeypatch.chdir(project) + monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False) + monkeypatch.delenv("CODEX_HOME", raising=False) + monkeypatch.setenv("PT_SNAP_SKILLS_DIR", str(REPO_ROOT / "skills")) + dest = tmp_path / "custom skills" + runner = CliRunner() + + installed = runner.invoke(app, ["skill", "install", "--dir", str(dest), "--json"]) + assert installed.exit_code == 0, installed.output + report = json.loads(installed.stdout) + assert report["restart_required"] is True + assert len(report["results"]) == 6 + assert {item["action"] for item in report["results"]} == {"installed"} + needed = "pt-snap-memory-leak" + skill_file = dest / needed / "SKILL.md" + assert skill_file.is_file() + if custom_status == "outdated": + skill_file.write_text("older skill instructions\n", encoding="utf-8") + elif custom_status == "missing": + skill_file.unlink() + skill_file.parent.rmdir() + + default = runner.invoke(app, ["skill", "list", "--json"]) + assert default.exit_code == 0, default.output + default_skills = json.loads(default.stdout)["skills"] + assert {item["status"] for item in default_skills} == {"missing"} + for item in default_skills: + assert (Path(item["source_dir"]) / "SKILL.md").is_file() + assert all(location["host"] != "custom" for location in item["locations"]) + + scoped = runner.invoke(app, ["skill", "list", "--dir", str(dest), "--json"]) + assert scoped.exit_code == 0, scoped.output + scoped_skills = {item["name"]: item for item in json.loads(scoped.stdout)["skills"]} + for name, item in scoped_skills.items(): + expected = custom_status if name == needed else "installed" + assert item["status"] == expected + assert item["locations"] == [ + {"host": "custom", "scope": "user", "path": str(dest / name), "status": expected} + ] + assert not list(home.iterdir()) + assert not list(project.iterdir())