skilltap

Getting Started ​

This guide walks you through installing skilltap, installing your first skill, setting up a tap, and configuring defaults.

Install skilltap ​

Download the standalone binary:

bash
curl -fsSL https://skilltap.dev/install.sh | sh

This puts the skilltap binary on your PATH. No runtime dependencies required.

Alternatively, if you have Bun installed:

bash
bunx skilltap

Verify the install:

bash
skilltap --version

Install your first skill ​

Install a skill from a git URL:

bash
skilltap install user/commit-helper

skilltap walks you through the process interactively:

◆ skilltap

◆ Which agents should this skill be available to?
│ ◼ Claude Code
│ ◻ Cursor
│ ◻ Codex
│ ◻ Gemini
│ ◻ Windsurf

◆ Save agent selection as default?
│ Yes

◇ Cloning user/commit-helper...
◇ Scanning commit-helper...
│ ✓ No warnings

◇ Install commit-helper?
│ › Yes

✓ Installed commit-helper → ~/.agents/skills/commit-helper/

Here's what happened:

  1. Scope was inferred automatically (smart-scope-default in v2.1): inside a git repo → project scope (.agents/skills/); outside → global (~/.agents/skills/). No prompt. Pass --project or --global to override.
  2. You selected which agents should see the skill (symlinks are created automatically)
  3. skilltap cloned the repo
  4. A static security scan checked all files for suspicious content
  5. No warnings found — you confirmed the install
  6. The skill was placed at ~/.agents/skills/commit-helper/ with a symlink in ~/.claude/skills/commit-helper/

If the scan had found warnings, skilltap would show them and offer to run a deeper semantic scan using your local AI agent before asking you to confirm.

Run non-interactively for CI / scripting via --agent (forces plain-text output, hard-fails on warnings, auto-yes for clean installs):

bash
skilltap install user/commit-helper --agent

--yes --global also works but doesn't activate the agent-mode security policy or plain-text output:

bash
skilltap install user/commit-helper --global --yes

To override the smart-scope inference, pass --global or --project:

bash
skilltap install user/commit-helper --global

Preview before installing

Use skilltap try <source> to clone, scan, and inspect a source repo without writing anything to your install paths. Useful for unfamiliar sources.

Coming from skilltap v0.x?

Run skilltap migrate once to convert your installed.json / plugins.json into the canonical state.json. A soft startup notice will remind you if v1 markers are detected.

During install, skilltap asks which agents the skill should be visible to. Your selection creates symlinks into agent-specific directories (e.g. ~/.claude/skills/). You can save your choice as the default for future installs.

The prompt is skipped automatically once you've saved a default (via skilltap config or "Save as default?" during a previous install). You can also skip it explicitly:

bash
skilltap install user/commit-helper --global --also claude-code

This creates:

  • ~/.agents/skills/commit-helper/ (the actual files)
  • ~/.claude/skills/commit-helper/ (symlink)

Supported agents: claude-code, cursor, codex, gemini, windsurf.

Add a tap ​

A tap is a curated index of skills -- a git repo containing a tap.json that lists skill names, descriptions, and URLs. Adding a tap lets you install skills by name instead of URL.

bash
skilltap tap add skilltap https://github.com/nklisch/skilltap-skills
Cloning tap...
✓ Added tap 'skilltap' (2 skills)

You can add as many taps as you want -- your own, a friend's, a team's.

Search and install from a tap ​

Search for skills:

bash
skilltap find

This opens an interactive search — type a query, browse results, and press Enter to install. You can also search directly:

bash
skilltap find review

Install by name:

bash
skilltap install skilltap --global

skilltap resolves the name from your configured taps, finds the repo URL, and runs the normal clone-scan-install flow.

You can also pin a version:

bash
skilltap install skilltap@v1.0.0 --global

View installed skills ​

bash
skilltap skills
Global (.agents/skills/) — 1 skill
  Name       Status   Agents       Source
  skilltap   managed  claude-code  https://github.com/nklisch/skilltap-skills

This shows all skills across all locations — managed, linked, and unmanaged. Filter by scope or status:

bash
skilltap skills --global       # only global skills
skilltap skills --project      # only project-scoped skills
skilltap skills --unmanaged    # only unmanaged skills (not tracked by skilltap)

For a broader dashboard that includes plugins, MCP injection, taps, and (in a project) manifest drift, run:

bash
skilltap status               # full dashboard
skilltap                       # alias for status
skilltap status --json         # machine-readable output for scripting

Adopt existing skills ​

If you've placed skills manually — copied them from a colleague, cloned them yourself, or inherited them from a project — they show up as unmanaged in skilltap skills:

bash
skilltap skills --unmanaged
Global (.agents/skills/) — 1 unmanaged skill
  Name           Status      Agents  Source
  commit-helper  unmanaged   —       ~/.agents/skills/commit-helper/

Unmanaged skills aren't source-tracked: skilltap can't update them, re-scan them, or tell where they came from. Use skills adopt to bring them under management:

bash
skilltap skills adopt

skilltap shows an interactive picker of all unmanaged skills. Select which ones to adopt, then choose how to handle them:

  • Move to ~/.agents/skills/ (default) — relocates files and records them with full source tracking
  • Track in place (--track-in-place) — records the skill at its current location without moving it
bash
# Adopt all unmanaged skills non-interactively
skilltap skills adopt --yes

# Track a skill at its current path without moving it
skilltap skills adopt my-skill --track-in-place

Once adopted, skills appear as managed in skilltap skills and are eligible for updates and security scans.

Move between scopes ​

Move a skill from project scope to global (or vice versa):

bash
skilltap skills move commit-helper --global

This relocates the files, updates state.json in both scopes, and refreshes any agent symlinks.

Update skills ​

Update all installed skills:

bash
skilltap update
◆ Checking commit-helper...
│ abc123 → def456 (2 files changed)
  M SKILL.md (+5 -2)
  A scripts/helper.sh (+18)

◇ Apply update to commit-helper?
│ › Yes
✓ Updated commit-helper

◆ Checking code-review...
│ Already up to date.

Updated: 1   Skipped: 0   Up to date: 1

Updates fetch the latest changes, show you a diff summary, scan the changed files for security issues, and ask before applying.

Update a specific skill:

bash
skilltap update commit-helper

Configure defaults ​

Run the interactive setup wizard:

bash
skilltap config

This walks you through:

  • Default install scope (global, project, or ask each time)
  • Which agents to auto-symlink to on every install

Your settings are saved to ~/.config/skilltap/config.toml. See the Configuration guide for the full reference.

Configure security ​

skilltap scans every skill for suspicious content before installing. You can fine-tune security with the dedicated wizard:

bash
skilltap config security

This lets you choose a preset (none, relaxed, standard, strict) or configure scan mode, warning behavior, and required scans individually -- with independent settings for human and agent modes. You can also set up per-tap trust overrides for internal taps you trust completely.

For non-interactive use (CI, scripting):

bash
skilltap config security --preset strict
skilltap config security --mode agent --preset none
skilltap config security --trust tap:my-company=none

See the Security guide for full details.

Next steps ​

  • Installing Skills -- all source formats, flags, scopes, and multi-skill repos
  • Creating Skills -- write and publish your own skills
  • Taps -- create and manage skill indexes
  • Sharing with a team -- the v2.0 project-manifest workflow (skilltap.toml + skilltap sync) for pinned, reproducible team setups
  • Security -- how scanning works and how to configure it
  • Configuration -- full config file reference, including --agent flag and SKILLTAP_AGENT=1 env var for CI/non-interactive use
  • Doctor -- 15 health checks for state, manifests, drift, MCP injection, and more
  • CLI Reference -- every command, flag, and option