Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 23 additions & 1 deletion docs/en/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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 '<skills_dir>' --json`, verify that same
directory with `pt-snap skill list --dir '<skills_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
Expand Down
20 changes: 19 additions & 1 deletion docs/zh/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` 会同时检查两个范围。

Expand Down Expand Up @@ -44,6 +44,24 @@ pt-snap skill uninstall --dir C:\Users\you\custom-skills

## 安装 skill

### 自定义目录可用性与 helper 交接

执行 `pt-snap skill install --dir '<skills_dir>' --json` 后,用
`pt-snap skill list --dir '<skills_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
Expand Down
49 changes: 47 additions & 2 deletions skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-name>/SKILL.md`, not the individual skill folder):

```bash
pt-snap skill list --dir '<skills_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:
Expand All @@ -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 <needed-skill> --dir '<skills_dir>' --json
pt-snap skill upgrade <needed-skill> --dir '<skills_dir>' --json
```

After any install, upgrade, or uninstall that changes skill files, the host
agent must be restarted before the change is visible:

Expand Down
49 changes: 47 additions & 2 deletions src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-name>/SKILL.md`, not the individual skill folder):

```bash
pt-snap skill list --dir '<skills_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:
Expand All @@ -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 <needed-skill> --dir '<skills_dir>' --json
pt-snap skill upgrade <needed-skill> --dir '<skills_dir>' --json
```

After any install, upgrade, or uninstall that changes skill files, the host
agent must be restarted before the change is visible:

Expand Down
84 changes: 84 additions & 0 deletions tests/skills/test_helper_availability.py
Original file line number Diff line number Diff line change
@@ -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 '<skills_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())
Loading