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
• Interactive Installer
• 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
• Plugin-exported skills from either skills/* or plugin/skills/*

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
• Interactive Node installer/status CLI for local bootstrap and client drift checks
• GitHub Actions CI plus PyPI release automation via Trusted Publishing

Support Matrix

Client	Status	Discovery root	Notes
Codex	Supported	~/.agents/skills	Respects existing aggregate custom exposures where already in place
Claude Code	Supported	~/.claude/skills	Injects explicit skill surfaces only
Copilot CLI	Supported	~/.copilot/skills	Injects explicit skill surfaces only

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

By default, install-plugin also uses native client plugin commands when the client CLI is available, so bundle-level hooks, MCP servers, and runtime metadata are installed by the client instead of only exposing SKILL.md files. Preview those native commands without running them:

skillpp install-plugin --publisher acme --name suite --repo acme/suite --native-dry-run

Use --no-native only when you intentionally want source-of-truth normalization and exported skill links without client-native plugin installation.

5. Create missing non-destructive exposures:

skillpp align --apply

6. Remove a managed custom skill after reviewing the dry run:

skillpp remove codex-mem
skillpp remove codex-mem --apply

7. Refresh managed repositories and git-backed bundles:

skillpp update

Interactive Installer

This repository also ships a local Node installer modeled after the skill-installer workflow. It is useful when you want a richer status table, interactive client selection, and dry-run output before changing anything.

Install the Node dependencies once:

npm install

Show client status without modifying anything:

node install.mjs --status

Preview the commands that would run:

node install.mjs --dry-run --yes

Run the interactive flow:

node install.mjs

Supported flags:

Flag	Effect
--status, -s	Show client status and exit
--dry-run, -n	Print install/update commands without running them
--yes, -y	Skip confirmation and select all eligible clients
--client <name>	Limit to claude, codex, or copilot; repeat for more
--help, -h	Show CLI help

The installer runs in auto mode:

• If plugin manifests are present, it uses each client's native plugin commands (plugin marketplace add, plugin install/update, or Codex plugin add).
• If plugin manifests are not present, it bootstraps this repository through the Python skillpp CLI and verifies the client discovery roots afterward.

Detection and status commands capture output. Install/update commands inherit the terminal so first-run trust prompts remain interactive. After a real install/update, the CLI verifies state again instead of trusting the command exit code alone.

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

Validate the Node installer surface:

npm run check

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.