skizl

imageLicense imageClaude Code imageAgent Plugins imageVersion

From scattered slash commands to a versioned, publishable skill library.

Pack. Version. Publish. Densify. One plugin to manage them all.

Your Claude Code skills deserve better than a flat folder.

As your skill library grows, flat folders stop working. You end up with 20 loose SKILL.md files — no shared context, no version history, no way to publish, no way to know what's installed where.

skizl is a cross-host skill lifecycle manager. It gives your skills the same workflows you'd expect from any serious package: organize into containers, wire up shortcuts, diff versions, snapshot before big changes, compress verbose skills into high-density micro-kernels, and publish to supported plugin formats through an agent workflow.

⚡ Quick Start

Install:

npx skills add alexsmedile/skizl

Pack related skills into a container:

/skizl pack write, summarize, and proofread skills into writing skill container

Wire every skill into Claude Code at once:

/skizl sym in

Snapshot before a big change:

/skizl snapshot skills/writing

Publish to the Claude + Codex marketplace:

/skizl publish skills/writing --username your-github-username

/skizl is a skill/plugin invocation shown to the agent host, not a terminal executable. Do not run skizl ... in a shell. In Codex, invoke the installed skizl:skill-manager skill and request the same lifecycle action in natural language.

Author, Harden & Densify Skills

This plugin includes a cohesive 4-skill suite:

• skill-manager: Full lifecycle management (pack, unpack, pin, sym, diff, snapshot, bump, publish, release, git-guard).
• skill-forge: Full authoring and audit workflow with routed tracks, architecture workshop, fresh-context review gate, and evals.
• skill-draft: Fast single-pass draft engine for small single-file skills.
• skill-densify: High-density 5-layer micro-kernel compressor that transforms verbose conversational skills into ≤65-line kernels with decision matrices and mechanical script offloading.

Each run picks an operation — Create (no usable skill yet), Update (a completed skill needs a behavioral delta), or Resume (an unfinished run continues from its recorded state). The operation says where the run starts; the track still says how much process the work needs. Resume reads a forge record kept outside the skill folder, so a new session picks up at the first incomplete gate instead of restarting or reopening settled decisions.

Before any folders are chosen, an architecture workshop maps boundaries, capability clusters, real runtime branches, and routing — so the scaffold follows how the skill actually runs rather than mirroring topic headings. It scales to the decision surface: a single-rule skill gets one paragraph, not a table. The review gate then runs a fresh-context full review, and — only if it found blockers — one issue-scoped verification, with two reviewer calls as the hard default.

📦 The Container Pattern

Instead of N folders with duplicated context, one container routes to on-demand action files. Only SKILL.md is loaded automatically — everything else is pulled when needed.

Before:

skills/
├── draft/SKILL.md
├── revise/SKILL.md
├── summarize/SKILL.md
└── proofread/SKILL.md

After:

skills/writing/
├── SKILL.md              ← routing + menu (<500 lines, auto-loaded)
├── references/
│   ├── draft.md          ← loaded on demand
│   ├── revise.md
│   ├── summarize.md
│   └── style-guide.md   ← shared knowledge, one place
└── scripts/
    └── pin.mjs

Benefits:

• One slash command (/writing) instead of four
• Shared knowledge lives in references/ — no duplication
• Master SKILL.md stays lean — no context bloat
• Pack and unpack are reversible copy operations — nothing is ever destroyed

🔧 Commands

All operations are non-destructive. Pack and unpack are copy operations — source files are never modified or deleted.

🧠 How It Works

skizl covers the full skill lifecycle in four phases:

Organize — pack collapses N standalone skills into one container with a references/ folder. unpack reverses it. pin creates a shortcut redirect so any container action is reachable as its own slash command.

Wire — sym in symlinks your entire skills/ directory into .claude/skills/ and .agents/skills/ using portable relative symlinks. list and doctor show you what's installed, linked, broken, or missing.

Version — snapshot saves the current SKILL.md as versions/SKILL@x.y.z.md before changes. bump increments the version field and offers to snapshot. diff compares two versions — and offers to snapshot if local is ahead. history lists all snapshots with --show and --diff flags. archive tarballs the whole skill folder when a diff shows large-scale changes.

Distribute — fork clones a skill from a local path or GitHub URL. publish scaffolds package/plugin manifests (.claude-plugin/, .codex-plugin/, .agents/plugins/, root plugin.json) from your SKILL.md frontmatter in one pass while preserving the portable runtime surface: direct skills/<name>/SKILL.md folders. release executes an atomic, verified, and resumable plugin release to GitHub and Codex.

📌 pin.mjs

scripts/pin.mjs automates pin/unpin without manual file creation. No external dependencies — standard Node.js only.

node scripts/pin.mjs --list skills/writing          # show active pins
node scripts/pin.mjs skills/writing draft           # create /i-draft pin
node scripts/pin.mjs --remove skills/writing draft  # remove pin
node scripts/pin.mjs --skills-dir ~/.claude/skills skills/writing draft

The script reads SKILL.md frontmatter to extract name, allowed-tools, and the action description. Pins are automatically symlinked into .claude/skills/ if that directory exists.

💾 Install & Consumption Models

Users choose their installation method based on their workflow:

Tip

Pick one method per skill/plugin. Never run a managed CLI installer over a directory that is already symlinked to a local development workspace.

For day-to-day skill-library installs, prefer direct skill folders in the host's canonical skill root (.agents/skills/, .claude/skills/, ~/.gemini/config/skills/, etc.). Plugin directories remain useful for validation and distribution, but do not assume a /skill picker recursively discovers nested plugins/<bundle>/skills/*.

Host-Specific Instructions

skizl ships a conformant Agent Plugins 1.0.0 manifest at its repo root — the open, vendor-neutral packaging standard maintained by AWS, Cursor, Microsoft, OpenAI, and Vercel, with Google as a Core Maintainer. Any host that reads the standard can install it directly from the repository. The per-runtime instructions below cover hosts that use their own format.

Claude Code — marketplace

/plugin marketplace add alexsmedile/skizl
/plugin install skizl@skizl

Or open the interactive /plugin manager and browse from there.

Codex — marketplace

Fastest — one command, activates the plugin directly:

npx codex-marketplace add alexsmedile/skizl --plugin

Or via the native Codex CLI — two commands, no interactive step:

codex plugin marketplace add alexsmedile/skizl
codex plugin add skizl@skizl

Or add the marketplace and browse interactively with codex /plugins.

Prefer a Git marketplace over a local one. codex plugin marketplace upgrade refreshes Git snapshots only — a marketplace added from a local path never updates, and its plugins stay pinned at the version you first installed.

Google Antigravity

For day-to-day skill-library use, install direct skill folders into the app's canonical skill root so /skill discovery sees each skill by name:

# global — Antigravity desktop app skill picker
mkdir -p ~/.gemini/config/skills
ln -s /path/to/skizl/skills/skill-manager ~/.gemini/config/skills/skill-manager
ln -s /path/to/skizl/skills/skill-forge ~/.gemini/config/skills/skill-forge
ln -s /path/to/skizl/skills/skill-draft ~/.gemini/config/skills/skill-draft
ln -s /path/to/skizl/skills/skill-densify ~/.gemini/config/skills/skill-densify

Antigravity also ships both a CLI and an app plugin surface. Use the plugin scan directories below only when validating or distributing the whole plugin bundle, not as the preferred /skill discovery install:

# workspace-level plugin bundle (this workspace only) — read by BOTH the app and the CLI
git clone https://github.com/alexsmedile/skizl .agents/plugins/skizl

# global plugin bundle — Antigravity 2.0 desktop app
git clone https://github.com/alexsmedile/skizl ~/.gemini/config/plugins/skizl

# global plugin bundle — agy CLI (separate state tree from the app)
git clone https://github.com/alexsmedile/skizl ~/.gemini/antigravity-cli/plugins/skizl

Caution

Never run agy plugin install on a symlinked plugin. It is destructive toward the link target. Either symlink/clone directly into the plugin scan directory OR install via CLI — never both.

The app and the CLI keep independent global roots, so a global install in one is not visible to the other. The workspace path is the only plugin location both scan. Do not assume nested plugin skills appear as top-level /skill entries; flatten skills into ~/.gemini/config/skills/ when discoverability matters.

npx skills

npx skills add alexsmedile/skizl       # project-scoped
npx skills add alexsmedile/skizl -g    # global

Test locally (no install)

git clone https://github.com/alexsmedile/skizl
claude --plugin-dir ./skizl                  # Claude Code
npx codex-marketplace add ./skizl --plugin   # Codex

Invoke as /skizl <command> after install. Run /skizl onboard if it's your first time.

Private repos and team sharing

Marketplaces are not public-only. Claude Code and Codex both git clone over HTTPS, so a private repo installs exactly like a public one as long as git can already authenticate. Once per machine:

gh auth login
gh auth setup-git    # routes HTTPS github.com clones through your gh token

Then the usual commands work unchanged against a private repo:

/plugin marketplace add yourorg/private-skills
/plugin install toolkit@private-skills

To share a skill with a team, publish it to a private org repo and grant access by GitHub team membership — distribution is governed by repo permissions, not by anything plugin-specific. Useful extras:

Teammates who skip gh auth setup-git see a failure that reads like a missing repo rather than a permission error — worth calling out, since it looks like a typo in the owner or repo name.

Who It's For

• Agent-skill authors with growing libraries who want structure without overhead
• Anyone building a skill container library to share or reuse
• Developers who want to author for Claude Code, Codex, Cursor, or Gemini and publish supported plugin formats

Who It's Not For

• Users with just a few skills — a flat folder works fine at small scale
• Workflows that require a standalone skizl terminal binary — skizl is an agent skill/plugin, not a CLI