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.9.6. 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. GitHub multi-skill collection preview/apply first shipped in v0.9.0. Collection-level update and one-step rollback are in Unreleased and are not part of the tagged v0.9.5 release.

A 75-second v0.9.5 overview built around one line: every scattered skill, collected into one library. It walks the Dashboard that manages every managed skill in one screen, the skill detail where one edit reaches every connected runtime, runtime-aware workspaces, review-before-write imports, and evidence-aware Calls with transparent coverage. Feature shots mount the real components from apps/desktop/src rather than screenshots; the usage data and deployment targets shown are demo fixtures.

The earlier 30-second v0.9.0 promo stays in the repository as that release's artifact.

• 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 changes in both directions. Inspect local user-skill diffs before commit/push. The shipped v0.7 line adds an explicit Check remote -> Review incoming changes -> Apply fast-forward flow for safe inbound updates; diverged history remains a normal Git conflict to resolve outside SkillBox.
• Evidence-aware Calls, references, and operation history. Count locally confirmed executions plus defensible structured invocations as Calls, keep lower-signal history references separate, and explain coverage 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.
• Git-backed local and GitHub collections. Import Review groups skills from the same local Git worktree or reviewed GitHub repository snapshot into one collection card while keeping each child independently importable, deployable, and usage-tracked. The current project UI makes one shared User/Remote choice in the collection header, then selects or clears all eligible children as a group; unresolved or mixed type state blocks selection and apply until you choose explicitly. GitHub preview/apply fetches one bounded ref, shows the resolved SHA and child status, and never deploys automatically. Collection-level update and one-step rollback are in Unreleased.
• Installed-source provenance. Copied skills with valid v3 installer lockfile entries can appear under one verified GitHub or HTTPS well-known source collection even without a local Git worktree. This is display-only provenance: it does not invent a branch, HEAD, or update authority, and each child keeps the normal reviewed per-skill import path.
• Compatibility before deployment. Rust-owned runtime profiles identify each workspace and report preserved frontmatter warnings or hard blockers before a confirmed symlink deployment.
• Signed macOS distribution. Install a notarized DMG or Homebrew cask and apply signed app updates only after confirmation.

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 profile-aware global and project-local SKILL.md roots for Agents, Codex, Claude Code, Cursor, and exact custom folders. Search by workspace name, path, or profile and combine the query with the existing scope filters.

Usage keeps a compact year heatmap of daily Calls and a Usage 统计 table. Click a day to filter that table to the day's skill totals. Its optional coverage disclosure separates confirmed and defensible inferred Calls from lower-signal History references, and reports the local provider scan boundary without presenting account analytics.

History separates Calls, history references, and management operations. The standalone Usage page defaults to all-time Calls, with 7-day and 30-day filters, plus skill type (User, Remote, or System), Agent, or Workspace. A year heatmap shows daily Call intensity; clicking a day updates the Usage 统计 table. Calls combine locally confirmed executions with defensible structured per-turn invocations; references never increase Calls or default ranking order. Usage keeps same-name regular and System skills separate and uses the observed source when preparing an import. Coverage reports confirmed, inferred, and reference totals, their time ranges, retained provenance sources, and the latest provider scan totals.

Sync histories imports auditable usage evidence from Codex, Claude Code, and Cursor without copying chat bodies. Codex per-turn <skill> blocks, [$skill](.../SKILL.md) links with an absolute path, and dedicated SKILL.md file reads (cat, sed, head, and similar) are inferred Calls, not provider-confirmed runs; catalog entries, prose, search/find commands, mixed tool payloads, and outputs are excluded. Claude Code native Skill tool/command attribution is confirmed after resolving a real SKILL.md, including skills that currently live in another local runtime or the managed store. Cursor state context.cursorRules entries are references. A structured assistant Read or ReadFile of an absolute local SKILL.md in a bounded Cursor agent transcript, and a user manually_attached_skills attachment, are inferred Calls, deduplicated once per transcript user turn and skill. Safe historical paths remain auditable after the file is moved or deleted, but never become filesystem or deployment authority. Repeated scans are idempotent and stronger evidence upgrades an existing event without losing provenance. The desktop app incrementally refreshes local histories hourly, shows Last sync time beside Usage page actions, and Sync histories is incremental too; skillbox usage-backfill-* --full still rescans every file. Codex local stores do not expose a stable provider-native run total, so local Calls remain a known undercount rather than account analytics. An incremental sync can recover or upgrade evidence from files that changed; database migration itself does not rescan histories.

GitHub installs and workspace deployments use a preview-first flow. A multi-skill GitHub review shows one repository/ref and one resolved SHA before any managed write. In the current project UI, one collection-header User/Remote decision resolves all actionable children, and the collection checkbox selects or clears only eligible children; imported, system, invalid, conflicted, and other read-only children remain unchanged. Each selected child is still imported, deployed, and usage-tracked independently, and nothing deploys automatically. Collection-level update and one-step rollback are in Unreleased.

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
• ~/.cursor/skills
• project-local .codex/skills
• project-local .agents/skills
• project-local .claude/skills
• project-local .cursor/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.

• Scan and register supported global or project-local SKILL.md workspaces. In the packaged macOS app, use the native single-directory picker or enter a path manually to choose a project or existing skills folder; SkillBox immediately runs a read-only preview, and can explicitly create exactly one selected .agents/skills, .codex/skills, .claude/skills, or .cursor/skills root before registration. Cancelling the picker changes nothing, and SkillBox never creates all runtime roots automatically.
• Review user, remote, and system import candidates before copying anything; the review shell opens immediately with staged scan progress, then shows one card per skill, every location and differing variant, and exactly one reviewed source without changing equivalent copies.
• 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.
• Preview runtime-profile and frontmatter compatibility before deploying to an individual workspace. Blocked targets cannot be selected, warnings require confirmation, and apply revalidates stale skill/target/profile state before creating an ownership-checked symlink.
• Delete a skill from the managed store and its SkillBox-owned workspace symlinks after a name-confirmed preview. Symlinks that point somewhere else stay on disk. A recovery backup and workspace registrations are retained, and a real non-symlink target still blocks deletion.
• Review user-skill Git diffs, create selected-file Conventional Commits, and optionally push. The v0.7 flow handles incoming origin/main changes through separate preview-confirmed fast-forward steps; SkillBox never auto-merges, rebases, resets, stashes, or resolves conflicts.
• During local Import Review, Rust detects the nearest safe Git worktree and presents its SKILL.md children as one collection. Collection scans are read-only; applying selected children rechecks the reviewed worktree/HEAD and stores collection provenance after the import succeeds.
• 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 hooks and structured local-history evidence; browse Calls separately from History references, inspect a year heatmap of daily Calls, rank by confirmed plus defensible inferred Calls, and inspect aggregate-only coverage 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 in the background at most once per day, show an Update action when a new macOS build is available, and install only after the user clicks it.

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

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.

Download the signed and notarized DMG from:

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

For this release, use the asset named:

SkillBox_0.9.6_universal.dmg

The matching checksum is published as:

SkillBox_0.9.6_universal.dmg.sha256

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

DMG installs check signed GitHub Releases in the background at most once per day. When a new version is available, use the Update action beside the SkillBox brand, confirm in the dialog, then SkillBox installs the signed update and restarts. You can also review release notes in Settings -> App updates. SkillBox never downloads or installs an app update without that confirmation.

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.

1. Open SkillBox.
2. Run Scan to discover known global and project-local skill workspaces, or use Add workspace to choose one local project or skills folder with the packaged app's native directory picker. You can still enter an absolute path manually. A selection immediately opens the read-only setup preview; cancelling the picker has no effect. Confirm only if you want to register an existing root or create the one selected supported project-local root.
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. SkillBox accepts standalone repository URLs with a root SKILL.md, root SKILL.md file URLs, and skill directory URLs. Repository-root snapshots exclude Git metadata.
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 add confirmed local execution evidence. Without complete hook/provider coverage, Calls remain a local lower bound.

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;
• in the v0.7 flow, explicitly fetch and preview incoming origin/main changes, then fast-forward the shared user-skills repository only after confirmation;
• when you click Generate in commit review, send the selected diff to a local commit-summary CLI (Cursor Agent by default, or a path you set in Settings);
• 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.

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

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.

• Roadmap
• Good first issues
• Architecture
• Data model
• Workflows
• CLI and Desktop capability matrix
• Implementation status
• Contributing
• Managed store ADR
• Symlink deployment ADR
• Rust core migration ADR
• Agent adapter ADR
• Usage evidence ADR
• Reviewed inbound Git ADR
• Git-backed Skill Collections ADR

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.

SkillBox is available under the MIT License.