SkillBox

Local-first skill management for SKILL.md agent runtimes.

English | 简体中文

Website | Releases | GitHub

SkillBox is a local-first macOS desktop app with a Rust core and CLI for managing SKILL.md-based skill and capability packages without treating any supported agent runtime as the source of truth.

Current release: v0.4.3. SkillBox is useful today for local skill management, but it is still early software. Keep backups of important skills, and review each filesystem change before applying it.

Promo Video

A 30-second overview of SkillBox: local-first skill management, review-before-import, remote updates, usage history, and GitHub-backed releases.

Why

• One managed store for supported runtimes. Keep durable skill state in ~/.skillbox, then deploy it into supported global or project-local SKILL.md roots.
• Review the whole lifecycle. Inspect imports, deployments, type changes, source bindings, updates, rollbacks, and deletion before SkillBox changes managed or runtime files.
• Versioned remote skills. Check GitHub sources while SkillBox is open, preview all-file diffs, apply updates, and roll back to immutable versions.
• Reviewed Git commit and push. Inspect user-skill diffs, create a Conventional Commit, and optionally push it; inbound divergence remains a normal Git conflict to resolve outside SkillBox.
• Real usage and operation history. Record supported agent hook calls and show them beside management operations without storing full chat transcripts.
• Safe storage and deployment defaults. Use ordered SQLite migrations, recovery backups, integrity checks, and ownership-checked symlinks instead of silently overwriting runtime content.
• Signed macOS distribution. Install a notarized DMG or Homebrew cask and apply signed app updates only after confirmation.

Screenshots

The dashboard provides local search, type/update/tag/favorite filters, grid and list views, and status-focused cards. The skill detail view collects workspace deployment, usage, version history, source binding, rollback, tags, type changes, and reviewed deletion in one place.

The Workspaces view tracks global and project-local SKILL.md roots across Codex CLI, Codex App, Claude Code skill folders, and project-specific runtimes. Search by workspace name, path, or agent and combine the query with Global/User filters.

History combines real skill calls and management operations. When a hook supplies prompt text, SkillBox stores a bounded excerpt of up to 500 characters rather than the full transcript; the excerpt can still contain user text.

Doctor checks the SQLite schema and integrity, managed skills, deployments, workspaces, and import backups. Diagnostics are read-only; stale deployment records require an explicit repair action.

Import review keeps local scans explicit: candidates are classified before SkillBox copies them into the managed store.

What SkillBox Manages

SkillBox keeps its managed store under ~/.skillbox by default:

~/.skillbox/
  user-skills/
    <skill-name>/
      SKILL.md
  remote-skills/
    <skill-name>/
      source.json
      current -> versions/<version>
      versions/
        <version>/
          SKILL.md
  backups/
  skillbox.sqlite

Runtime directories are deployment targets:

• ~/.codex/skills
• ~/.agents/skills
• ~/.claude/skills
• project-local .codex/skills
• project-local .agents/skills
• project-local .claude/skills

Longer-term support for native Claude, OpenClaw, Cursor, Claude Code, Copilot, and other non-SKILL.md formats should go through explicit agent adapters rather than hard-coded UI behavior.

Features

• Scan and register supported global or project-local SKILL.md workspaces, then search them by name, path, or agent and filter by scope.
• Review user, remote, and system import candidates before copying anything; conservatively revert eligible deploy-back imports.
• Install GitHub-backed skills through a preview/apply flow and bind discovered remote source candidates without replacing the active version.
• Check remote sources, preview all-file diffs, apply updates, and roll back to immutable versions.
• Deploy or remove managed skills in individual workspaces through ownership-checked symlinks; migrate User/Remote ownership and retarget deployments through a reviewed flow.
• Delete a skill from the managed store and all associated workspaces after a name-confirmed preview, while retaining a recovery backup and workspace registrations.
• Review user-skill Git diffs, create selected-file Conventional Commits, and optionally push without attempting an inbound auto-merge.
• Search and filter the dashboard by type, update status, tag, or favorite; switch between grid and list views, with favorites and tags persisted in SQLite.
• Record supported Codex App, Codex CLI, and Claude Code CLI hook calls, and browse usage beside management operations without storing full transcripts.
• Apply ordered SQLite migrations with pre-migration backups and integrity checks; run Doctor diagnostics and explicitly clean up stale deployment records.
• Check signed GitHub Releases and install macOS app updates only after user confirmation.

Requirements

• macOS 14 Sonoma or newer
• Git, for user-skill sync and remote skill workflows
• An agent runtime that uses SKILL.md directories

Windows, Linux, and a Homebrew CLI formula are not part of the current release.

Public website telemetry

The public SkillBox website uses optional VibeLoft page-view telemetry only after a visitor opts in. The website integration is separate from the macOS app and CLI: it cannot access managed skills, prompts, runtime folders, or the local SkillBox database. See the website privacy notice for the transmitted fields and opt-out controls.

Install

GitHub Releases

Download the signed and notarized DMG from:

https://github.com/santosli/SkillBox/releases

For this release, use the asset named:

SkillBox_0.4.3_universal.dmg

The matching checksum is published as:

SkillBox_0.4.3_universal.dmg.sha256

Open the DMG and drag SkillBox.app into /Applications.

DMG installs can use Settings -> App updates to check signed GitHub Releases and install updates after confirmation.

Homebrew

The cask uses the project tap instead of the official Homebrew Cask repository:

brew tap santosli/tap
brew install --cask skillbox

Upgrade with:

brew upgrade --cask skillbox

Uninstall with:

brew uninstall --cask skillbox

Homebrew uninstall does not delete ~/.skillbox.

First Run

1. Open SkillBox.
2. Run Scan to discover known global and project-local skill workspaces.
3. Use Import to review candidates before SkillBox copies them into ~/.skillbox.
4. Use Install to preview GitHub-backed remote skills, then confirm before SkillBox copies them into the managed store.
5. Deploy managed skills to selected runtime workspaces when you want an agent to use them.
6. Optional: enable usage hook injection in Settings to record real skill calls.

Permissions And Local Changes

SkillBox is local-first and does not require a hosted account. The app may:

• scan known runtime directories for SKILL.md folders;
• write managed copies and metadata under ~/.skillbox;
• create symlinks from runtime directories back to managed skills;
• initialize and update Git metadata for ~/.skillbox/user-skills;
• modify supported runtime hook config files when you explicitly inject hooks.

SkillBox treats runtime folders, GitHub URLs, downloaded archives, and existing skills as untrusted input. It should not silently overwrite a non-symlink runtime target.

Uninstall And Reset

See docs/uninstall-reset.md for removing the app, reverting hook injection, deleting runtime symlinks, and optionally removing the managed store.

Architecture

React desktop UI
  -> Tauri commands
  -> skillbox-core / skillbox-github / skillbox-git
  -> local filesystem, SQLite, Git, and structured GitHub source metadata

Workspace layout:

apps/desktop/              Tauri + React desktop app
apps/desktop/src-tauri/    Tauri command bridge
crates/skillbox-core/      managed skill lifecycle, safety, SQLite, workspaces, history, hooks, and Git sync
crates/skillbox-github/    GitHub skill URL parsing and normalization
crates/skillbox-git/       structured Git service boundary
crates/skillbox-cli/       Rust CLI
docs/                      architecture, data model, workflows, ADRs

New core business logic should go into Rust crates. React should call structured Tauri commands instead of owning filesystem, Git, GitHub download, migration, or rollback behavior.

Docs

• Roadmap
• Good first issues
• Architecture
• Data model
• Workflows
• Implementation status
• Contributing
• Managed store ADR
• Symlink deployment ADR
• Rust core migration ADR
• Agent adapter ADR

Development

See CONTRIBUTING.md for local setup, test commands, release invariants, and contribution guidelines. New contributors can start with Good first issues or the public Roadmap.

Useful commands:

npm test
cargo test --offline
npm --workspace apps/desktop run build
npm run docs:check-staged

For UI changes, also run the Vite or Tauri app and verify the affected screen manually.

License

SkillBox is available under the MIT License.