Skip to content

feat: add pt-snap skill CLI for shared agent skill install - #132

Merged
codeasier merged 5 commits into
mainfrom
feat/skill-cli-management
Sep 17, 2026
Merged

codeasier merged 5 commits into
mainfrom
feat/skill-cli-management

Conversation

@codeasier

Copy link
Copy Markdown
Owner

📝 Description

Add CLI-only pt-snap skill commands 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 codex keep the host-native extras; --dir covers 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 added/updated
  • Focused local pytest against worktree sources (tests/core/test_skill_service.py, tests/test_cli.py::TestSkillCommands, tests/test_completion.py, tests/test_bundled_skills.py)
  • Manual testing completed

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    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-cli on branch feat/skill-cli-management. Main checkout is clean of these changes.

codeasier added 2 commits September 14, 2026 20:50
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 codeasier left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Treat existing paths that lack SKILL.md as outdated, validate catalog names,
and keep SkillService catalog lookup hermetic to the injected environment.
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread pyproject.toml Resolved
@codeasier

codeasier commented Sep 14, 2026 •

Copy link
Copy Markdown
Owner Author

Cross-review summary

This 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 0adfb54 before posting. 6 findings survived verification: 2 Medium, 4 Low — posted as inline comments.

# Severity Finding Location
1 Medium upgrade can silently rmtree a non-skill directory that collides with a bundled skill name src/pt_snap_cli/core/skill_service.py:309
2 Medium Multi-target install mutates earlier destinations, then aborts on the first conflict with no partial report src/pt_snap_cli/core/skill_service.py:126
3 Low Publication is not atomic (remove-before-replace); mkdir outside error translation src/pt_snap_cli/core/skill_service.py:601
4 Low Untranslated OSError in catalog enumeration / digest computation src/pt_snap_cli/core/skill_service.py:529
5 Low Fixed staging name allows concurrent installs to interfere src/pt_snap_cli/core/skill_service.py:597
6 Low Packaging ships only bundled_skills/*/SKILL.md while install/digest use the whole directory pyproject.toml:65

Verified as correct (no findings): frontmatter name traversal is blocked by _SKILL_NAME_PATTERN and tested; yaml.safe_load is used; _remove_path is symlink-safe; CLI test isolation is real; skill commands stay off the MCP server as documented.

Residual testing gaps: no multi-host conflict test (finding 2), no OSError translation tests (findings 3-4), no concurrency test (finding 5), no wheel-content packaging test (finding 6).

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.
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread src/pt_snap_cli/core/skill_service.py Resolved
Comment thread tests/test_bundled_skills.py Resolved
@codeasier

Copy link
Copy Markdown
Owner Author

Follow-up cross-review (head ad23732)

Follow-up review of the fix commits by the same 3-model cross-review (3/3 reviewers succeeded this round), with each verdict independently verified against the new head.

All 6 original findings verified fixed (finding 3 partially — OSError translation complete, publication window narrowed but still remove-before-replace):

# 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.
@codeasier

Copy link
Copy Markdown
Owner Author

Follow-up cross-review round 3 (head 5f1905c)

Same 3-model cross-review (3/3 succeeded), parent-session verified.

Fixes verified for the 6 round-2 findings:

# 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.

@codeasier
codeasier merged commit b6aef07 into main Sep 17, 2026
6 checks passed
@codeasier codeasier mentioned this pull request Sep 17, 2026
6 of 7 tasks
@codeasier
codeasier deleted the feat/skill-cli-management branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant