Metadata-Version: 2.5
Name: skills-manager-cli
Version: 0.1.1
Summary: A CLI to handle agent skills
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.12
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# ai-skills-manager

[![PyPI](https://img.shields.io/pypi/v/skills-manager-cli?style=flat-square)](https://pypi.org/project/skills-manager-cli/)
[![Python](https://img.shields.io/pypi/pyversions/skills-manager-cli?style=flat-square)](https://pypi.org/project/skills-manager-cli/)
[![License: MIT](https://img.shields.io/pypi/l/skills-manager-cli?style=flat-square)](LICENSE)

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](https://typer.tiangolo.com/).

## Requirements

- Python 3.12 or newer
- `git`
- `pip` or [`uv`](https://docs.astral.sh/uv/) (either works; examples below
  show both)

## Install

```sh
pip install skills-manager-cli
```

or, if you use [`uv`](https://docs.astral.sh/uv/):

```sh
uv tool install skills-manager-cli
```

Then verify:

```sh
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):

```sh
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:

```sh
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):

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

```powershell
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:

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

```powershell
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:

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

```powershell
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):

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

Install a skill everywhere at once:

```sh
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:

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

Keep skills fresh:

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

Remove cleanly:

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

Keep the tool itself current:

```sh
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):

```sh
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:

```sh
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:

```sh
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:

```toml
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`](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`](docs/technical.md) — CI runners, execution-log
  format, configuration internals, development setup
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to contribute (setup, workflow,
  merge checklist)
- [`docs/backlog.md`](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`](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.
