ai-skills-manager

One command to install, track, and update agent skills across every AI coding agent on your machine — with lockfile-based team sharing and built-in security scans.

• Install once, active everywhere — fetch skills from Git repositories, a GitHub owner/repo shorthand, or a local folder, pick what you want, and it lands in every enabled agent in one step.
• Stay fresh — see what has upstream updates, pull them everywhere in one shot, or schedule a daily refresh.
• Share with your team — install into a project as a committable skills-lock.json; teammates import it and get the same skills.
• Stay safe — every install and update is security-scanned before anything is written to disk.

Supported agents: Claude Code (claude), OpenCode (opencode), Codex (codex), Cursor (cursor), and Gemini CLI (gemini). Only agents found on your machine are used; the rest are ignored. Built with Typer.

Requirements

• Python 3.12 or newer
• git
• pip or uv (either works; examples below show both)

Install

pip install skills-manager-cli

or, if you use uv:

uv tool install skills-manager-cli

Then verify:

skills-manager --help

If your shell cannot find it, add the user binary directory to PATH (the installer prints the exact line when this applies):

export PATH="$HOME/.local/bin:$PATH"  # then re-login or re-source

Done with the tool? Uninstalling removes the package but keeps your home data (~/.skills-manager) in place:

pip uninstall skills-manager-cli

Alternative: install scripts

Prefer scripts (e.g. offline mirrors or a pinned source checkout)? Clone and run them — they pick uv first when both installers are present (needs a GitHub account with access to the repo):

git clone https://github.com/alecvinent/ai-skills-manager.git
sh ai-skills-manager/install.sh

git clone https://github.com/alecvinent/ai-skills-manager.git
.\ai-skills-manager\install.ps1

Once the repository is public, these one-liners work instead:

curl -fsSL https://raw.githubusercontent.com/alecvinent/ai-skills-manager/main/install.sh | sh

irm https://raw.githubusercontent.com/alecvinent/ai-skills-manager/main/install.ps1 | iex

Prefer to inspect first? Download the script, read it, then run it with sh install.sh (or install.ps1 in PowerShell). A custom source works too: SKILLS_MANAGER_REPO=<git-url> sh install.sh.

The matching uninstall scripts remove the installed package and executable (via pip or uv, whichever installed it) and keep your home data in place:

git clone https://github.com/alecvinent/ai-skills-manager.git
sh ai-skills-manager/uninstall.sh

git clone https://github.com/alecvinent/ai-skills-manager.git
.\ai-skills-manager\uninstall.ps1

Once the repository is public, raw one-liners work for these too (.../main/uninstall.sh | sh, .../main/uninstall.ps1 | iex).

First steps

Pick which agents receive skills (skills stay installed when you toggle):

skills-manager agent                    # show detected agents and states
skills-manager agent claude --disable   # stop linking into Claude Code

Install a skill everywhere at once:

skills-manager install addyosmani/agent-skills --global   	# GitHub owner/repo shorthand
skills-manager install https://github.com/example/repo.git  # full URL
skills-manager install ./my-skills --all                    # local path, no picking
skills-manager install ./my-skill                           # a folder whose own SKILL.md is the skill

A source is usually a collection (every folder with a SKILL.md, at any depth, installs as one skill under its own folder name); a source whose SKILL.md sits at its own root installs as a single skill named after the source. A skill name appearing in several places is a clear error instead of a silent overwrite.

See what is installed and where:

skills-manager list
# demo (global)
# demo (/path/to/a/project)

Keep skills fresh:

skills-manager check    # what has upstream updates (read-only)
skills-manager update   # pull updates into every copy

Remove cleanly:

skills-manager uninstall demo        # confirm once, gone everywhere
skills-manager uninstall --all       # remove everything

Keep the tool itself current:

skills-manager upgrade --check   # report only, changes nothing
skills-manager upgrade           # verify + swap the binary in place

Working on a project with teammates

Install into the project so the result is committable (.agents/skills plus a skills-lock.json entry with no machine-specific paths):

cd my-project
skills-manager install addyosmani/agent-skills --local
git add .agents/skills skills-lock.json && git commit -m "Add skills"

Teammates adopt the lockfile (theirs or an npx skills one) with:

skills-manager import               # defaults to the current directory
skills-manager import /path/to/dir  # or point at one explicitly

Adopted a project by other means? Register whatever is already on disk:

skills-manager sync   # scans the configured locations, registers finds

Scopes

• Global (default) — the skill is active everywhere; installing fetches and activates it in every enabled agent.
• Local (--local) — writes a committable project install (.agents/skills plus a lockfile entry) so teammates get it from the lockfile.

A skill installed globally is globally active — there is no separate "fetch without activating" step. Uninstalling a skill's last install removes it entirely.

Security scans

Every install/update scans fetched content first: high/critical findings block by default (--minimum-accepted-severity adjusts the ceiling), --unsafe-install proceeds anyway while still printing every finding, and --exclude / --exclude-path record manual-review exceptions that updates reapply. scan reports the same findings without installing. Outcomes land in the daily execution log.

Commands

Command	Description
install [<url|owner/repo|path>] [id...] [--all] [--as <name>] [--ref <ref>] [--global|--local]	Install into every enabled agent — straight from a repo URL, a GitHub owner/repo shorthand, or a path (fetch + pick + install in one step), or by the id of an already-installed skill to add another scope/project. Default scope is global; --local writes the committable project install. Interactive pickers if no id; --all skips them. Link failures warn instead of rolling back the install. Scans fetched content first: findings above --minimum-accepted-severity (default medium, so high/critical) block; --unsafe-install proceeds anyway while still printing every finding; --exclude / --exclude-path record manual-review exceptions.
import [dir]	Adopt a project's skills-lock.json into skills-manager's tracking: fetch the sources and write any missing copies/links.
uninstall [id...] [--all] [--global|--local]	Unlink everywhere and delete the global and project copies + lock entries + registry entry (interactive picker if no id). --global / --local remove only that scope; removing the last scope removes the skill entirely.
unregister [id...]	Drop the tracking (registry + lockfile entries) without touching copies or links (interactive picker if no id).
list	Show every installed skill and where it is installed (global or the project path) — one <name> (<location>) line per install, or No skills installed. when empty. Read-only.
filter <topic>	List installed skills matching a topic (case-insensitive substring on name and frontmatter description): one executive-summary block per match (name, description, opening body lines, capped). Read-only.
info <id|source>	Show everything tracked about one installed skill — source, kind, ref, revision, locations, and linked agents — or about every skill recorded from a source (owner/repo, URL, path, or repo name). Read-only.
check	Report which git skills have upstream updates. Read-only.
scan <source>	Report security findings for a source's skills without installing (exit 1 when blocked by policy). Read-only.
update [id]	Pull updates for outdated git skills (all, or one), writing the new content into every install — the global copy and every tracked project's copies and lock entries — and adopt teammate-added lockfile entries. Scans fetched content first: findings above --minimum-accepted-severity (default medium, so high/critical) block; --unsafe-install proceeds anyway while still printing every finding; --exclude / --exclude-path record manual-review exceptions that updates reapply.
schedule [--install|--remove] [--time HH:MM]	Manage a daily skills-manager --yes update entry (default 09:00) in the platform scheduler; bare run reports status. The installed time is kept in skills-manager.conf (--time wins, then the conf value). Read-only unless installing/removing.
agent [name] [--enable|--disable]	Show agents, or enable/disable one, reconciling its links right away (skills stay installed). Interactive picker when run bare on a terminal.
upgrade [--check]	Upgrade skills-manager itself to the latest release: download this platform's archive, verify its SHA256 against the release's checksums.txt, and swap the binary in place. --check only reports.
sync	Scan the common paths listed in skills-manager.conf for already-installed skills and register any it finds. Skills are copied + recorded even when agent linking fails (e.g. Windows symlink privilege); link problems print as warnings and doctor reports the missing links for later repair. Always ends with a stdout summary (registered X, Y failed).
doctor	Report drift between disk, links, and records (missing copies, dead links, unknown lock entries). Read-only.
prune	Drop cached sources no install references, reporting what went away.
regenerate-config	Rewrite skills-manager.conf from the effective settings (warns and asks before overwriting an existing file).

Run skills-manager <command> --help for exact flags; skills-manager --help lists everything.

On interactive terminals, the long commands (install, update, import, sync, upgrade) print a progress line as each skill or stage starts; piped or scripted output stays exactly as documented.

Global flags

--force / --yes skip confirmations. --home <path> overrides the home directory (default ~/.skills-manager) so you can keep separate setups. --dry-run reports what a command would change without changing anything. --version prints the running version and exits.

Global flags work before or after the command: skills-manager --yes install <src> and skills-manager install <src> --yes mean the same.

Configuration & logs

skills-manager.conf (TOML) in the home directory is the single place for settings — currently the skill search paths and the disabled-agent list:

search_paths = ["/home/user/.agents/skills", "/home/user/.claude/skills"]

[agents]
disabled = ["cursor"]

Missing or empty file: built-in defaults apply (common agent skill locations, all agents enabled). Every run also appends one line to a daily execution log under the home (<home>/logs/YYYY-MM-DD.log). Path rules (including Windows), file-creation details, and the full log format live in docs/technical.md.

update vs upgrade

skills-manager update pulls new revisions of your installed skills; skills-manager upgrade replaces the skills-manager tool itself. A source install (or an unstamped build) matches no published release, so upgrade reports that and leaves it alone.

On interactive runs the tool also checks for a new release by itself at most every 12 hours and prints a one-line notice pointing at upgrade when one is available. The check never runs piped, for --dry-run, for the upgrade command itself, or for unstamped builds — and it can never fail or slow down your command.

More documentation

• docs/technical.md — CI runners, execution-log format, configuration internals, development setup
• CONTRIBUTING.md — how to contribute (setup, workflow, merge checklist)
• docs/backlog.md — the full spec source and roadmap

Roadmap & workflow

This project is spec-driven: every feature starts as a BL-xxx item in docs/backlog.md and flows through the spec-kit pipeline (specify → plan → tasks → analyze → implement → converge) defined in .specify/memory/constitution.md. All backlog items are built; the table above is the shipped surface.