skillpp 0.1.2

Audit-first skill and plugin management for Codex, Claude Code, and Copilot CLI.

Keep ~/.skills as the source of truth, export only the discovery surfaces each client should see, and repair drift without guessing hidden client state.

Repository: skill-install-plus-plus | Package: skillpp | CLI: skillpp

Table of Contents

• Why This Exists
• What Skillpp Manages
• Highlights
• Support Matrix
• Install
• Quick Start
• Source-of-Truth Model
• Why Audit-First Matters
• Development
• Release Model
• Contributing
• Security
• License

Why This Exists

AI assistant skill setups drift quickly once you mix:

• standalone local skill folders
• Git-backed skill repositories
• hybrid repositories that export skills plus bundle metadata
• plugin bundles with manifests, agents, hooks, and runtime files

Copies go stale, links diverge, and it becomes unclear which files are managed versus accidental.

skillpp gives those assets one managed home under ~/.skills, then projects only the explicit SKILL.md surfaces into client discovery roots.

It is intentionally conservative: audit first, mutate second.

What Skillpp Manages

• Standalone local skills normalized into ~/.skills/custom
• Git-backed skill repositories stored under ~/.skills/repos/<owner>/<repo>
• Plugin bundles stored under ~/.skills/plugins/<publisher>/<name>
• Explicit skill exposures for Codex, Claude Code, and Copilot CLI
• Non-destructive alignment when client discovery roots drift away from managed state

Highlights

• One managed source-of-truth tree under ~/.skills
• Supports standalone skills, Git-backed repos, hybrid repos, and plugin bundles
• Audit-first workflow for drift, broken links, legacy copies, and missing exposures
• Safe alignment that creates missing links without rewriting unrelated client state
• Public Python CLI available through uvx, uv tool install, and pipx
• GitHub Actions CI plus PyPI release automation via Trusted Publishing

Support Matrix

Install

Try it without installing

uvx skillpp audit

Persistent install with uv

uv tool install skillpp

Persistent install with pipx

pipx install skillpp

Quick Start

1. Audit the current managed state:

skillpp audit

2. Bootstrap the current project into the managed tree:

skillpp bootstrap --source .

3. Install a skill from GitHub:

skillpp install --repo jackwener/OpenCLI --path skills/opencli-browser

4. Install a plugin bundle:

skillpp install-plugin --publisher acme --name suite --repo acme/suite

5. Create missing non-destructive exposures:

skillpp align --apply

6. Refresh managed repositories and git-backed bundles:

skillpp update

Source-of-Truth Model

Everything managed by skillpp lives under ~/.skills:

~/.skills/
|- custom/
|- repos/<owner>/<repo>/
|- plugins/<publisher>/<name>/
`- registry.json

Client discovery roots stay separate:

• Codex: ~/.agents/skills
• Claude Code: ~/.claude/skills
• Copilot CLI: ~/.copilot/skills

This keeps the managed tree explicit while preserving each client's discovery model.

Why Audit-First Matters

Blind installers are convenient until they overwrite something you needed.

skillpp treats that as a design problem, not a user problem. The tool:

• inventories managed sources before mutating discovery roots
• surfaces legacy copies and mismatched links explicitly
• creates only safe missing links during alignment
• avoids guessing undocumented client plugin registries

That boundary matters most for larger bundles where exported SKILL.md files are only one part of the package surface.

Development

Run the test suite:

uv run python -m unittest tests.test_manager tests.test_cli -v

Build the package:

uv run --with build python -m build

Check built artifacts:

uv run --with twine python -m twine check dist/*

Release Model

skillpp is PyPI-first.

Recommended usage modes:

• uvx skillpp ... for ephemeral runs
• uv tool install skillpp for persistent installs
• pipx install skillpp as a familiar Python CLI alternative

There is no npm package or npx wrapper in v1.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for development workflow, test expectations, and contribution scope.

Security

Security reporting guidance lives in SECURITY.md.

License

MIT. See LICENSE.