Skillbox

English | 简体中文

Skillbox keeps a large local collection of Codex skills and activates only the skills that each project needs.

It is intentionally small and conservative:

• Scanning stays local; GitHub content is downloaded only for update checks or a user-confirmed update.
• Ordinary scan, selection, and cleanup commands do not delete original skills.
• It keeps hidden and system folders such as .system untouched.
• It backs up the current Codex skill folders before every use.
• It uses links on macOS and Linux, and permission-free directory copies on Windows.
• Permanent deletion requires a verified source and exact confirmation.

Requirements

• Windows 10/11, macOS, or Linux
• Python 3.10 or newer
• Git
• Codex with user skills stored under ~/.agents/skills or ~/.codex/skills

Install

The recommended installation uses pipx, which keeps Skillbox isolated from other Python tools:

pipx install git+https://github.com/Lingchen97/skillbox.git

If you use uv, install it with:

uv tool install git+https://github.com/Lingchen97/skillbox.git

Confirm the installation:

skillbox --version

Upgrade a pipx installation:

pipx upgrade codex-skillbox

Remove it:

pipx uninstall codex-skillbox

Uninstalling the command does not remove your registered skills, configuration, or backups from ~/.skillbox.

Quick Start

Discover and register skills already installed on your computer:

skillbox scan

If your skills live elsewhere, search your home directory:

skillbox scan --all

Open the local dashboard from a project directory:

cd /path/to/project
skillbox ui

Select the skills for that project, then click 应用所选. Skillbox saves the selection in .skillbox.toml, creates a backup, and activates the selected skills.

The same flow is available from the command line:

cd /path/to/project
skillbox init diagnose playwright
skillbox use
skillbox status

Project Configuration

Each project can declare its skills in .skillbox.toml:

skills = [
  "diagnose",
  "playwright",
  "superpowers:brainstorming",
]

Skills discovered inside a grouped folder are registered as group:skill, so collections can contain skills with duplicate names.

Global skills are stored separately by Skillbox and are activated for every project. A project does not need a .skillbox.toml when it only uses global skills. Global selections can be managed from the dashboard.

Commands

Command	Purpose
skillbox scan	Register skills from known local locations
skillbox scan --all	Find skills across the user directory
skillbox list	List registered skills
skillbox init [skills...]	Create the current project's selection
skillbox add <skill>	Add a skill to the current project
skillbox remove <skill>	Remove a skill from the current project
skillbox status	Show global, configured, and active skills
skillbox use	Back up current skills and activate the selection
skillbox restore	Restore the latest pre-use backup
skillbox prune --dry-run	Preview registry cleanup
skillbox prune	Move unused untrusted copies to a recoverable backup
skillbox delete <skill>	Permanently delete verified user-selected sources
skillbox ui	Open the local dashboard

Run skillbox <command> --help for command-specific options.

Scanning

The default scan reads:

~/.codex/skills
~/.agents/skills
~/.cc-switch/skills
~/.skillbox/backups

Pass custom sources when needed:

skillbox scan \
  --source ~/.codex/skills \
  --source ~/.agents/skills

Limit a deep scan to a particular directory:

skillbox scan --all --root ~/.codex/superpowers

Deep scans skip known caches, backups, application internals, marketplaces, downloads, and project workspaces. Scanning also records original sources so a user-added skill can later be deleted deliberately.

Dashboard

skillbox ui starts a dashboard on the local computer. It can:

• switch between local projects;
• scan known locations or run a filtered deep scan;
• show configured, active, global, and missing skills;
• check public GitHub sources and show skills with updates;
• associate a skill with GitHub and apply a selected update;
• add or remove project and global skills;
• apply a selection or restore the latest backup;
• clean up unwanted registered copies;
• permanently delete verified user skills;
• generate Chinese skill summaries with the local Codex model.

The dashboard listens only on 127.0.0.1. If a browser does not open, Skillbox prints the local URL.

Generated Chinese summaries are saved in ~/.skillbox/descriptions.zh.json; original skill folders are not modified. To use a different local model command, set SKILLBOX_SUMMARY_COMMAND. The command receives the prompt on standard input and must return a JSON object that maps skill names to Chinese summaries.

GitHub updates

The dashboard checks for updates after it opens and also provides a manual refresh button. Skillbox automatically recognizes skills scanned from a local GitHub checkout. A GitHub URL can also be declared in SKILL.md with one of these frontmatter fields: github, github_url, repository, repository_url, source_url, or homepage. Skills without recognized metadata can be linked from the dashboard using either a repository URL or an exact skill-directory URL.

When the dashboard starts, Skillbox also restores known GitHub sources from ~/.agents/.skill-lock.json and the local CC Switch database. Existing manual associations always take precedence, and CC Switch entries keep their recorded skill directory and branch.

Only public GitHub repositories are supported. A skill is marked as updated only when files inside that skill directory change. System and plugin-managed skills remain read-only. When several registered skills share one local GitHub checkout, updating one refreshes every registered skill from that checkout and the dashboard shows the full affected list before confirmation.

If local changes are detected, Skillbox requires confirmation and saves the old content under ~/.skillbox/update-backups/ before replacing it. Clean updates are staged and validated before any local directory is replaced. GitHub source records, cached checks, and downloaded repository data are stored under ~/.skillbox/.

Safety and Recovery

skillbox use manages these Codex-visible folders by default:

~/.agents/skills
~/.codex/skills

Before changing them, Skillbox copies their ordinary contents into a timestamped backup. Hidden and system folders remain untouched. Restore the most recent backup with:

skillbox restore

On macOS and Linux, activated skills are links to the registered collection. On Windows, they are ordinary directory copies so Developer Mode or administrator access is not required. Run skillbox use again after a scan if you want to refresh an already active Windows copy.

remove changes only the current project's selection. delete is separate and permanent: it lists recorded sources, asks which ones to delete, previews the additional Skillbox copies and usage records, then requires the exact skill name as confirmation.

For non-interactive deletion:

skillbox delete diagnose \
  --source ~/.agents/skills/diagnose \
  --confirm diagnose

Marketplace, plugin-generated, hidden, and system sources are protected. Other projects are not rewritten and will report a deleted skill as missing. External backups and version-control history are outside Skillbox's scope.

Preview broad-scan cleanup before moving anything:

skillbox prune --dry-run
skillbox prune

Storage and Environment Variables

Default storage:

~/.skillbox/skills/             registered skill collection
~/.skillbox/global.toml         global skill selection
~/.skillbox/backups/            pre-switch backups
~/.skillbox/sources.json        verified original sources
~/.skillbox/deletions.jsonl     deletion results, without skill contents
~/.skillbox/descriptions.zh.json generated Chinese summaries
~/.skillbox/github-origins.json recorded public GitHub sources
~/.skillbox/github-updates.json latest update-check results
~/.skillbox/update-backups/     backups made before confirmed updates

Override storage with SKILLBOX_HOME. Override managed Codex folders with CODEX_SKILLS_DIRS, separated by : on macOS/Linux or ; on Windows. The older single-folder CODEX_SKILLS_DIR setting is also supported.

Test without touching real skill folders:

SKILLBOX_HOME=/tmp/skillbox-home \
CODEX_SKILLS_DIRS=/tmp/codex-skills \
skillbox list

PowerShell equivalent:

$env:SKILLBOX_HOME = "$env:TEMP\skillbox-home"
$env:CODEX_SKILLS_DIRS = "$env:TEMP\codex-skills"
skillbox list

Development

Clone the repository and run the local wrapper:

git clone https://github.com/Lingchen97/skillbox.git
cd skillbox
python -m skillbox.cli --version
python3 -m unittest discover -s tests

The project has no runtime dependencies outside the Python standard library.

License

Skillbox is released under the MIT License.