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
10 changes: 9 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,15 @@ templates under category subdirectories are included by
Agent Skills hosts) plus Claude's independent `~/.claude/skills` or
`$CLAUDE_CONFIG_DIR/skills`. `--target cursor` and `--target codex` keep
the host-native extras; `--dir` covers anything else. List reports
`installed`, `outdated`, or `missing`. Skill management is CLI-only.
`installed`, `outdated`, or `missing`. Unfiltered `pt-snap skill uninstall`
(no `--target`, `--project`, or `--dir`) removes every installed or outdated
copy that list would report and that contains `SKILL.md`, across all
built-in hosts and both scopes. A same-named path without `SKILL.md`
aborts the whole unfiltered uninstall before any deletion.
`uninstall_skills(all_locations=True)` rejects dest_dir, hosts, and
scope other than `user`. `--target` / `--project` / `--dir` keep the
narrower mutation destinations.
Skill management is CLI-only.

### Snapshot import and split

Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@

### 修复

- `pt-snap skill uninstall` 在不带 `--target` / `--project` / `--dir` 时,会删除 `skill list` 报告的、且含有 `SKILL.md` 的每一份已安装或过期副本(全部内置宿主、用户级与项目级)。此前只检查默认的用户级 `agents` 与 `claude` 目录,因此 `cursor:user` 或 `--project` 副本会留下并继续显示为 `installed`。`--target` / `--project` / `--dir` 仍只作用于指定目标。同名但缺少 `SKILL.md` 的路径不会删除,并且会让整次卸载在动手前失败。部分名称未安装时,会在默认用户级 `agents` 与 `claude` 上报告 `not_installed`。
- `query --template-info` 在模板不存在时走与其他 CLI 失败相同的 `_error()` 路径,退出码为 1(此前 `typer.Exit()` 默认 0)。
- 未声明的 `--params` 键不再静默进入渲染上下文(例如 `min_sze` 不再当成未过滤结果);查询在渲染 SQL 前失败,并列出已接受参数名。
- `allocation` / `block` / `event` / `active_blocks_at_event` 的 `order_by`、`order_dir` 不再接受任意 SQL 片段;非法取值在进数据库前被拒绝,而不再以 SQLite syntax error 暴露。
Expand All @@ -38,6 +39,7 @@
- 依赖 `pt-snap-cli[rag]` 的安装命令会失败;该 extra 从未启用任何功能。
- 拼错或多余的查询参数、以及不在 `choices` 内的 `order_by` / `order_dir` 现在会报错,而不再静默得到错误结果或 SQLite 语法错误。
- 用户自写查询模板若在 `output_schema` 列上使用未登记键,加载会失败;仅含 `column`/`type` 的旧模板仍然有效。`execute_query()` 返回字典新增 `template`、`semantics_version` 键。
- 不带 `--target` / `--project` / `--dir` 的 `pt-snap skill uninstall` 现在会删除 `skill list` 看到的、含有 `SKILL.md` 的全部已安装副本,而不再只检查默认的用户级 `agents` 与 `claude` 目录。需要窄范围卸载时请显式传这些选项。同名但缺少 `SKILL.md` 的路径会让整次卸载失败且零删除。
- 本版本未扩展 `--json` 覆盖面。当前支持 `--json` 的是 `metadata`、`report peak-memory`,以及 `skill list` / `install` / `upgrade` / `uninstall`。`query`、`focus`、`import`、`split`、`config` 仍无 `--json`;`--template-info` 的机器可读形态仍是结构化 API dict 与 CLI 文本。

## [0.3.0] - 2026-09-17
Expand Down
9 changes: 7 additions & 2 deletions docs/en/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ pt-snap skill list --target claude --user
Each bundled skill is shown as its own block: name, status, install locations, and a short description. Status is one of:

- `installed` — a matching copy is present in at least one inspected location
- `outdated` — a copy exists but differs from the bundled skill
- `outdated` — a copy exists but differs from the bundled skill, or the path exists without `SKILL.md`
- `missing` — no copy was found

`--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 @@ -67,11 +67,16 @@ pt-snap skill upgrade pt-snap-setup --target claude

```bash
pt-snap skill uninstall
pt-snap skill uninstall pt-snap-setup
pt-snap skill uninstall pt-snap-setup --target claude
pt-snap skill uninstall --project --target cursor
```

`uninstall` removes bundled skill directories that contain `SKILL.md`. Skills that are not installed are reported as `not_installed`. A same-named path that exists without `SKILL.md` is left untouched.
Without `--target`, `--project`, or `--dir`, `uninstall` removes every bundled-skill copy that contains `SKILL.md` and that `list` would report as installed or outdated, across all built-in hosts and both user and project scopes. Each requested name with no removable copy is reported as `not_installed` at the default user-level `agents` and `claude` destinations. Omitting names requests every bundled skill.

`--target`, `--project`, and `--dir` keep narrower destinations: `--project` uses the default `agents` and `claude` project directories unless `--target` selects hosts, and `--dir` only touches that folder.

`uninstall` only deletes directories that contain `SKILL.md`. `list` also marks a same-named path without `SKILL.md` as `outdated`. Uninstall leaves that path untouched and, if any such path is among the destinations, refuses the whole operation before deleting anything. Remove or replace the stray path, then re-run uninstall.

After an install, upgrade, or uninstall that changes skill files, restart the agent so it picks up the change.

Expand Down
9 changes: 7 additions & 2 deletions docs/zh/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ pt-snap skill list --target claude --user
每个随包 skill 单独一块显示:名称、状态、安装位置,以及一句简短说明。状态为以下之一:

- `installed` — 至少一个检查位置存在内容匹配的副本
- `outdated` — 已有副本,但与随包版本不同
- `outdated` — 已有副本但与随包版本不同,或路径存在但没有 `SKILL.md`
- `missing` — 未找到副本

`--target` 接受逗号分隔的 `agents`、`claude`、`cursor`、`codex`。`--user` 和 `--project` 分别只检查用户级或当前项目目录。不传这些选项时,`list` 会同时检查两个范围。
Expand Down Expand Up @@ -67,11 +67,16 @@ pt-snap skill upgrade pt-snap-setup --target claude

```bash
pt-snap skill uninstall
pt-snap skill uninstall pt-snap-setup
pt-snap skill uninstall pt-snap-setup --target claude
pt-snap skill uninstall --project --target cursor
```

`uninstall` 会删除已经包含 `SKILL.md` 的随包 skill 目录。未安装的 skill 会报告为 `not_installed`。同名路径存在但没有 `SKILL.md` 时不会删除。
不带 `--target`、`--project` 或 `--dir` 时,`uninstall` 会删除 `list` 会报告为已安装或过期、且含有 `SKILL.md` 的每一份随包 skill 副本,覆盖全部内置宿主以及用户级和项目级目录。每个没有可删除副本的请求名称,会在默认的用户级 `agents` 和 `claude` 目录上报告 `not_installed`。省略名称表示请求全部随包 skill。

`--target`、`--project` 和 `--dir` 仍只作用于更窄的目标:`--project` 默认使用 `agents` 和 `claude` 项目目录,可用 `--target` 改宿主;`--dir` 只处理该文件夹。

`uninstall` 只删除已经包含 `SKILL.md` 的目录。`list` 也会把同名但没有 `SKILL.md` 的路径标为 `outdated`。卸载不会删除这类路径;只要目标中出现任何一处,就会在删除任何副本之前整次拒绝。先自行移除或替换该杂散路径,再重新卸载。

仅在 install、upgrade 或 uninstall 实际改动 skill 之后,才需要重启 agent 让变更生效。`list` 不会提示重启。

Expand Down
8 changes: 6 additions & 2 deletions skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,12 @@ Repository `skills/*/SKILL.md` is the authoring source. Wheel installs read
same `SKILL.md` into that packaged tree. `pt-snap skill list`, `install`,
`upgrade`, and `uninstall` manage copies in the shared `.agents/skills`
tree, Claude's independent directories, optional Cursor/Codex extras, or
an explicit `--dir`. After install or upgrade, the host agent must be
restarted.
an explicit `--dir`. Unfiltered `uninstall` (no `--target`, `--project`,
or `--dir`) removes every installed copy that `list` would report and
that contains `SKILL.md`. A same-named path without `SKILL.md` aborts
the whole unfiltered uninstall before any deletion.
`--target` / `--project` / `--dir` keep narrower destinations. After
install or upgrade, the host agent must be restarted.

## Focused Tests
- Run `pytest tests/skills/test_helper_contract.py` after helper-skill changes.
Expand Down
14 changes: 12 additions & 2 deletions src/pt_snap_cli/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -889,7 +889,10 @@ def skill_uninstall(
typer.Option(
"--target",
"-t",
help="Comma-separated hosts: agents,claude,cursor,codex (default: agents,claude)",
help=(
"Comma-separated hosts: agents,claude,cursor,codex. "
"Defaults to agents,claude when --project is set"
),
autocompletion=complete_skill_targets,
),
] = None,
Expand All @@ -905,15 +908,22 @@ def skill_uninstall(
] = None,
json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON")] = False,
) -> None:
"""Remove bundled agent skills from shared agent, Claude, Cursor, Codex, or custom directories."""
"""Remove bundled agent skills.

Without --target, --project, or --dir, remove every SKILL.md copy that
`pt-snap skill list` would report. A same-named path without SKILL.md
aborts the whole uninstall. Use those flags to limit destinations.
"""
custom_dir = _skill_dest_dir(dest_dir, target, project=project)
service = _skill_service()
try:
unfiltered = custom_dir is None and target is None and not project
report = service.uninstall_skills(
names,
hosts=None if custom_dir is not None else parse_host_option(target),
scope="project" if project else "user",
dest_dir=custom_dir,
all_locations=unfiltered,
)
except (
SkillCatalogError,
Expand Down
42 changes: 41 additions & 1 deletion src/pt_snap_cli/core/skill_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -155,8 +155,20 @@ def uninstall_skills(
hosts: Iterable[str] | None = None,
scope: str = "user",
dest_dir: Path | str | None = None,
all_locations: bool = False,
) -> SkillInstallReport:
jobs = self._mutation_jobs(names, hosts, scope, dest_dir)
if all_locations:
if dest_dir is not None or hosts is not None or self._resolve_scope(scope) != "user":
raise InvalidSkillTargetError(
"Removing every installed copy cannot be combined with "
"--target, --project, or --dir."
)
jobs = self._discovered_uninstall_jobs(names)
missing = self._undiscovered_uninstall_names(names, jobs)
if missing:
jobs.extend(self._mutation_jobs(missing, None, "user", None))
else:
jobs = self._mutation_jobs(names, hosts, scope, dest_dir)
for spec, _host, _selected_scope, dest in jobs:
if _non_skill_destination(dest):
raise SkillInstallError(_non_skill_delete_message(spec.name, dest))
Expand Down Expand Up @@ -251,6 +263,34 @@ def _mutation_targets(
for host in selected_hosts
]

def _discovered_uninstall_jobs(
self, names: Iterable[str] | None
) -> list[tuple[SkillSpec, SkillHost, SkillScope, Path]]:
catalog = {spec.name: spec for spec in self.list_catalog()}
requested = self._resolve_names(names, catalog)
jobs: list[tuple[SkillSpec, SkillHost, SkillScope, Path]] = []
seen: set[Path] = set()
for name in requested:
spec = catalog[name]
for selected_scope in SKILL_SCOPES:
for host in SKILL_HOSTS:
dest = self._host_root(host, selected_scope) / name
if dest in seen or not (dest.exists() or dest.is_symlink()):
continue
seen.add(dest)
jobs.append((spec, host, selected_scope, dest))
return jobs

def _undiscovered_uninstall_names(
self,
names: Iterable[str] | None,
jobs: list[tuple[SkillSpec, SkillHost, SkillScope, Path]],
) -> list[str]:
catalog = {spec.name: spec for spec in self.list_catalog()}
requested = self._resolve_names(names, catalog)
discovered = {spec.name for spec, _host, _selected_scope, _dest in jobs}
return [name for name in requested if name not in discovered]

def _location_status(
self, spec: SkillSpec, host: SkillHost, scope: SkillScope
) -> SkillLocationStatus:
Expand Down
97 changes: 97 additions & 0 deletions tests/core/test_skill_service.py
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,103 @@ def test_uninstall_removes_installed_skill(service: SkillService) -> None:
assert again.results[0].action == "not_installed"


def test_all_locations_uninstall_removes_every_listed_copy(
service: SkillService,
) -> None:
service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user")
service.install_skills(["pt-snap-demo"], hosts=("agents", "claude"), scope="project")
cursor = service.skill_destination("cursor", "user", "pt-snap-demo")
agents_project = service.skill_destination("agents", "project", "pt-snap-demo")
claude_project = service.skill_destination("claude", "project", "pt-snap-demo")

report = service.uninstall_skills(["pt-snap-demo"], all_locations=True)
actions = {(item.host, item.scope, item.action) for item in report.results}
assert actions == {
("cursor", "user", "uninstalled"),
("agents", "project", "uninstalled"),
("claude", "project", "uninstalled"),
}
assert not cursor.exists()
assert not agents_project.exists()
assert not claude_project.exists()


def test_all_locations_uninstall_reports_default_not_installed(
service: SkillService,
) -> None:
report = service.uninstall_skills(["pt-snap-demo"], all_locations=True)
actions = {(item.host, item.scope, item.action) for item in report.results}
assert actions == {
("agents", "user", "not_installed"),
("claude", "user", "not_installed"),
}


def test_all_locations_uninstall_reports_missing_names_among_discovered(
service: SkillService,
) -> None:
service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user")

report = service.uninstall_skills(["pt-snap-demo", "pt-snap-other"], all_locations=True)
actions = {(item.name, item.host, item.scope, item.action) for item in report.results}
assert actions == {
("pt-snap-demo", "cursor", "user", "uninstalled"),
("pt-snap-other", "agents", "user", "not_installed"),
("pt-snap-other", "claude", "user", "not_installed"),
}
assert not service.skill_destination("cursor", "user", "pt-snap-demo").exists()


def test_default_python_uninstall_stays_on_install_destinations(
service: SkillService,
) -> None:
service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user")
service.install_skills(["pt-snap-demo"], hosts=("agents",), scope="project")

report = service.uninstall_skills(["pt-snap-demo"])
actions = {(item.host, item.scope, item.action) for item in report.results}
assert actions == {
("agents", "user", "not_installed"),
("claude", "user", "not_installed"),
}
assert (
service.skill_destination("cursor", "user", "pt-snap-demo").joinpath("SKILL.md").is_file()
)
assert (
service.skill_destination("agents", "project", "pt-snap-demo")
.joinpath("SKILL.md")
.is_file()
)


def test_all_locations_uninstall_rejects_target_project_or_dir(
service: SkillService, tmp_path: Path
) -> None:
with pytest.raises(InvalidSkillTargetError, match="--target, --project, or --dir"):
service.uninstall_skills(["pt-snap-demo"], hosts=("claude",), all_locations=True)
with pytest.raises(InvalidSkillTargetError, match="--target, --project, or --dir"):
service.uninstall_skills(["pt-snap-demo"], dest_dir=tmp_path / "skills", all_locations=True)
with pytest.raises(InvalidSkillTargetError, match="--target, --project, or --dir"):
service.uninstall_skills(["pt-snap-demo"], scope="project", all_locations=True)


def test_all_locations_uninstall_refuses_before_mutating_conflict(
service: SkillService,
) -> None:
service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user")
dest = service.skill_destination("claude", "project", "pt-snap-demo")
dest.mkdir(parents=True)
notes = dest / "notes.txt"
notes.write_text("keep me\n", encoding="utf-8")

with pytest.raises(SkillInstallError, match="Refusing to delete"):
service.uninstall_skills(["pt-snap-demo"], all_locations=True)
assert (
service.skill_destination("cursor", "user", "pt-snap-demo").joinpath("SKILL.md").is_file()
)
assert notes.is_file()


def test_human_skill_summary_keeps_first_sentence() -> None:
text = (
"Collect a snapshot by dumping a `.pkl` file. Not for diagnosing an "
Expand Down
Loading
Loading