gskill

GSKILL

Reproducible package management for AI agent skills.

GSKILL installs, versions, locks, verifies, and restores SKILL.md-based AI agent skills across Claude Code, Codex, Cursor, Gemini CLI, developer machines, and CI. Commit skills-lock.json; teammates and CI reproduce a byte-identical skill environment anywhere with gskill install --frozen-lockfile.

Why GSKILL

AI agent skills — SKILL.md instruction bundles — are usually installed by hand: cloned into a dotfile directory, copied between projects, upgraded whenever someone remembers. That leaves no record of what's installed, no way to verify it wasn't tampered with, and no way to reproduce it on a second machine or in CI. GSKILL treats skills like dependencies: resolved, content-hashed, locked, and restorable byte-for-byte from a single committed file.

Key features

• Reproducible installs — skills-lock.json records intent and resolved reality together; --frozen-lockfile restores exactly, or fails closed.
• Verified integrity — every install is checked against a recorded content hash; gskill verify re-checks on demand; skill content is never executed.
• Multi-agent, one store — a skill is resolved and stored once and shared by every agent that targets it, via symlinks (or copies where unsupported).
• Scriptable — every capability is reachable from the CLI, with --json output and documented exit codes for CI.
• Signed releases — checksummed, cosign-signed archives with SBOMs and build-provenance attestations.

Supported agents and platforms

gskill ships for Linux and macOS on amd64 and arm64. Windows is not supported. See Supported agents for detection and scope details.

Quick start

Install (pick one):

# Install script — downloads the right archive and verifies its checksum
curl -sSfL https://raw.githubusercontent.com/glapsfun/gskill/main/scripts/install.sh | sh

# Homebrew (macOS and Linux)
brew install glapsfun/tap/gskill

# Go (requires a Go toolchain)
go install github.com/glapsfun/gskill/cmd/gskill@latest

Verify the install with gskill version.

Use it:

gskill init                                                      # prepare .gskill/ + .agents/skills/
gskill add github.com/owner/repo --skill example --agent claude  # resolve, install, lock
gskill install --frozen-lockfile                                 # reproduce exactly elsewhere
gskill verify                                                    # re-hash installed content vs the lock

Commit skills-lock.json — it's the only project state file GSKILL writes; it records both what you asked for and what was resolved, so anyone can reproduce it with gskill install --frozen-lockfile.

Core workflow

GSKILL's lifecycle is discover → add → lock → install → verify → update.

1. Discover

Search for available skills:

gskill search kubernetes

2. Add

Resolve, install, and record a skill:

gskill add github.com/example/skills --skill kubernetes --agent claude

3. Lock

Every add/install/update writes the resolution to skills-lock.json automatically — there's no separate lock step to remember.

4. Install

Reproduce a locked environment elsewhere, exactly:

gskill install --frozen-lockfile

5. Verify

Re-hash installed content against the lock:

gskill verify

6. Update

Advance within your version constraints and re-lock:

gskill update

Common examples

Install a skill for one agent:

gskill add github.com/example/skills --skill security-review --agent claude

Install for multiple agents:

gskill add github.com/example/skills --skill security-review --agent claude,codex

Restore a cloned project:

gskill install --frozen-lockfile

Preview changes:

gskill install --dry-run

Check project health:

gskill status
gskill verify

Update skills:

gskill outdated
gskill update

Documentation

Full documentation lives in docs/, organized by the Diátaxis framework:

• Tutorial: Getting started — from an empty directory to a reproducible skill environment.
• How-to guides — task-focused recipes.
• Reference — commands, exit codes, configuration, and the lockfile/frontmatter schemas.
• Explanation — the reproducibility model, integrity and trust, the store, and multi-agent installs.
• Contributing — the TDD workflow and quality gate for anyone changing GSKILL itself.

Project status and compatibility

GSKILL is under active development. The current release is v0.2.0 (pre-1.0). It supports Linux and macOS on amd64 and arm64; Windows is not currently supported. It targets Claude Code, Codex, Cursor, and Gemini CLI. The lockfile format (skills-lock.json) is versioned; breaking CLI or schema changes may occur before v1.0 and are documented in release notes.

init, add, onboard, install (incl. --frozen-lockfile/--offline), verify, check, outdated, update, remove, sync, repair, list, info, search, diff, doctor, cache, config, completion, and dashboard (tui) all work today against Git and local sources.

Security and integrity

Every install is verified against a recorded content hash before it's written; a mismatch aborts rather than partially installing. Skill content is data, never executed. Release artifacts are checksummed, cosign-signed, and shipped with SBOMs and build-provenance attestations — see Cut and verify a release to verify them yourself. Read Integrity and trust for the full model.

Contributing

GSKILL is developed test-first behind a single quality gate (./scripts/verify.sh), enforced identically for local development, git hooks, and CI. See docs/contributing/development.md for the full workflow, one-time setup, and script reference.

License

MIT