Repository navigation
feat: add pt-snap skill CLI for shared agent skill install - #132
Conversation
Give agents a packaged way to install, list, upgrade, and uninstall bundled skills into the shared ~/.agents/skills tree and Claude's independent directories.
codeasier
left a comment
There was a problem hiding this comment.
Cross-Review Summary
Independent multi-model review (2 reviewers: volceapi/qwen3.8-flash, jiyuan/deepseek-flash; a third timed out and was excluded), consolidated and verified against the PR head 5d399c6 snapshot.
Overall: solid staging-based publication, clean CLI/service separation, MCP untouched as claimed, and bundled-vs-repo skill copies enforced identical by tests/test_bundled_skills.py.
Verified findings (inline below):
| # | Severity | Summary |
|---|---|---|
| 1 | Medium | install silently deletes a pre-existing destination lacking SKILL.md, bypassing the documented --force gate |
| 2 | Low (security) | Frontmatter name is used unvalidated as a path component — install/uninstall can escape the skills root |
| 3 | Low | Malformed skill frontmatter raises an uncaught yaml.YAMLError (traceback + broken shell completion) |
| 4 | Low | PT_SNAP_SKILLS_DIR is read from global os.environ, bypassing the injected environ (non-hermetic, undocumented); parse_name_option is dead code |
Considered and rejected: uninstall removing locally-modified copies without --force/digest check — explicit removal is standard package-manager behavior; design choice, not a regression.
Missing tests: destination existing without SKILL.md; traversal-shaped frontmatter names; malformed frontmatter; install --dir + --project at the CLI level.
Treat existing paths that lack SKILL.md as outdated, validate catalog names, and keep SkillService catalog lookup hermetic to the injected environment.
Cross-review summaryThis PR was cross-reviewed by independent reviewer models (2 of 3 succeeded; one failed on upstream API errors and was isolated), with every candidate finding independently verified against the PR head
Verified as correct (no findings): frontmatter Residual testing gaps: no multi-host conflict test (finding 2), no |
The previous collision fix marked same-named paths without SKILL.md as outdated, which made upgrade delete user data. Preflight every host before publishing so a later conflict cannot leave a partial install.
Follow-up cross-review (head
|
| # | Original finding | Verdict |
|---|---|---|
| 1 | upgrade rmtree-ing non-skill destinations |
Fixed — _non_skill_destination pre-check + re-check, tested |
| 2 | partial mutation on conflict, no report | Fixed for conflicts — pre-flight before any write, tested |
| 3 | non-atomic publish + mkdir outside translation |
Partially fixed — mkdir translated + tested; remove→replace window remains |
| 4 | untranslated OSError |
Fixed — iterdir/rglob/read_bytes translated, tested |
| 5 | fixed staging-name race | Fixed — uuid4 staging suffix |
| 6 | packaging only SKILL.md |
Fixed — bundled_skills/**/* + full-tree parity test |
No regressions found in 0adfb54..ad23732: snapshot provenance untouched (PR decision correct), MCP stays skill-free, CLI exception handling and test isolation verified by all reviewers.
New findings from the follow-up (posted inline): 1 Medium — uninstall still rmtrees non-skill directories without the guard install/upgrade just gained (pre-existing, not a regression); 5 Low — remove-before-replace residual, shutil.move fallback can nest staging inside a re-created destination, except-cleanup can mask the translated error, mid-loop I/O failure still discards partial reports, and the packaging test is a text assertion only.
Uninstall used the same rmtree path install/upgrade just gated, so a same-named directory without SKILL.md was deleted. Publish now renames the old copy aside and restores it if replace fails.
Follow-up cross-review round 3 (head
|
| # | Round-2 finding | Verdict |
|---|---|---|
| 1 | [Medium] uninstall rmtree-ing non-skill destinations |
Fixed — pre-flight + per-job _non_skill_destination guard, tested |
| 2 | [Low] non-atomic remove-before-replace publish | Fixed — copytree → dest.replace(backup) → staging.replace(dest) atomic swap with _restore_destination rollback, tested |
| 3 | [Low] shutil.move fallback nesting staging |
Fixed — fallback removed entirely |
| 4 | [Low] except-cleanup masking the translated error | Fixed — cleanup via _safe_remove (OSError-suppressed) |
| 5 | [Low] mid-loop I/O failure discards partial report | Still open — see reply in thread |
| 6 | [Low] packaging test is a text assertion | Still open — see reply in thread |
No regressions in ad23732..5f1905c (guard ordering, symlink safety, hidden staging/backup handling all verified by 3/3 reviewers).
Notes (non-blocking): the two-rename swap leaves a hidden backup dir if the process crashes between renames (crash-only scenario); no test forces the cleanup paths to raise to pin the non-masking behavior of finding 4.
Findings 5 and 6 are Low-severity, deferred with follow-up replies in their threads.
📝 Description
Add CLI-only
pt-snap skillcommands so agents can list, install, upgrade, and uninstall the bundled setup/collection/diagnostic skills.Default install writes the shared Agent Skills tree (
~/.agents/skills,.agents/skills) plus Claude's independent directories. Cursor, OpenCode, and current Codex read the shared tree;--target cursor/--target codexkeep the host-native extras;--dircovers custom or Windows paths. Restart is hinted only after an install, upgrade, or uninstall that actually changes files.Skill management is not exposed on MCP.
🔗 Related Issue
N/A
🧪 Testing
tests/core/test_skill_service.py,tests/test_cli.py::TestSkillCommands,tests/test_completion.py,tests/test_bundled_skills.py)✅ Checklist
Snapshot Runtime Provenance
Snapshot provenance decision: no-update
Snapshot provenance no-update reason: This PR does not change
src/pt_snap_cli/snapshot/**.📋 Additional Notes
Worktree:
.worktrees/feat-skill-clion branchfeat/skill-cli-management. Main checkout is clean of these changes.