# Install skp with an AI agent

Give this file or its URL to your coding agent and say:

> Read this guide, install and configure skp on my machine, then verify
> that it works and show me how to use it.

中文提示词：

> 请阅读这份文档，在我的本机安装并配置 skp，验证安装结果，并告诉我怎么使用。

## Instructions for the agent

Complete the installation, configuration, bundled skill setup, and verification
below. This guide is self-contained; a repository checkout is optional.

skp is a local CLI installed once for the current OS user. It can manage skills
across multiple agents through the `agent_dirs` configuration.
Skill files live in a vault, and enabled skills are
symlinked into the directories agents scan. Installing the CLI alone is not the
full setup: also enable its bundled `skp` skill so future sessions can use it.
Keep existing skills available during setup. Migrating them into profiles is a
separate, optional step.

Repository: <https://github.com/ni00/skp>

## 1. Inspect the environment

- Use macOS, Linux, or a Linux environment such as WSL. skp requires Python 3.11+
  and POSIX filesystem support, including symlinks and file locking; native
  Windows is unsupported.
- Check whether `skp` already exists with `command -v skp`, `skp --version`,
  `skp help`, and `skp skill`. Reuse a working installation. Do not upgrade or
  replace it merely because this guide was supplied again.
- Check for `uv`, `pipx`, Git, and a suitable Python interpreter. Use an available
  installer below. If a prerequisite is missing, use the environment's normal
  installation method; if unavailable, report the specific blocker.
- Respect an existing `SKP_HOME`; otherwise the vault is `~/.skills-vault`.
  Expand `~` and resolve relative paths before using them in filesystem operations.
- Identify the installed agents' actual skills directories from their configuration
  and the environment. Common paths are `~/.codex/skills`, `~/.agents/skills`,
  and `~/.claude/skills`. Once the CLI is installed, `skp scan --json` discovers
  existing user roots, including `.cursor/skills`, `.zocde/skills`, and
  `.pi/agent/skills`, and reports each skill's entry point. Inspect symlinks rather
  than assuming these directories are aliases. Use the user's requested scope when provided; otherwise include
  the skills directories identified for agents in use on this machine. If the
  scope cannot be determined, ask which directories skp should manage.

## 2. Install the CLI

Choose **one** route. These commands install from the project's repository so
this file also works without a local checkout. Git is required for Git URLs.

With uv:

```sh
uv tool install 'git+https://github.com/ni00/skp.git'
```

With pipx:

```sh
pipx install 'git+https://github.com/ni00/skp.git'
```

From an existing checkout of this repository, use `uv tool install .` or
`pipx install .` in the checkout instead. Honor a user-requested version or Git
ref instead of silently selecting another version.

If neither tool installer is available, use a dedicated virtual environment
with Python 3.11+ (choose a different path if this one already belongs to
something else):

```sh
python3 -m venv "$HOME/.local/share/skp/venv"
"$HOME/.local/share/skp/venv/bin/python" -m pip install 'git+https://github.com/ni00/skp.git'
```

For uv or pipx, use `uv tool update-shell` or `pipx ensurepath` if their executable
directory is missing from PATH. For the venv route, add its `bin` directory to
the user's shell PATH without duplicating an existing entry. Use the installed
executable's absolute path in the current shell until PATH is available. Do not
use `sudo pip` or replace an unrelated executable named `skp`.

Run `skp --version` and `skp help` successfully before continuing.

## 3. Initialize or reuse the configuration

The config is `<vault>/profiles.toml`; state is `<vault>/state.json`.

- If the config does not exist, run `skp init`. It creates an empty `base`
  profile with no active profile and includes discovered user directories.
  Review the generated `agent_dirs` and set it
  to the skills directories identified in step 1. A single skp installation and
  vault serve all configured directories.
- If the config already exists, read it and run `skp list --json` and
  `skp status --json`. Preserve profiles, active selection, overlay, and existing
  directory choices. Do not rerun `init`, reset the vault, or replace the config
  with an example. Back up config and state outside the vault before editing.
  Use `skp scan --register` when the requested scope includes newly discovered
  roots; registration alone does not move skills or change links.
- `agent_dirs` must not overlap with the vault or each other. Relative entries
  resolve against the vault, not the current working directory. Aliases resolving
  to the same directory are deduplicated.
- Run from the user's project and inspect `project` / `project_error` in JSON.
  A nearest `.skp` limits allowed profiles and overlays; honor it during setup.
  The links remain user-wide. Creating `.skp` alone does not switch the profile.

Do not run `skp adopt --all` during default installation. Existing real skill
directories and symlinks pointing outside the vault can stay in place; skp calls
these entries `foreign`. They remain available to the agent.

## 4. Install and enable the bundled agent skill

1. Run `skp skill`. Its output is a **directory**, not a Markdown file. Verify
   that it contains `SKILL.md`; copy the entire directory to `<vault>/skp` if
   that destination is absent. For a source installation missing packaged data,
   use the checkout's `skills/skp` directory. Do not link to a disposable checkout
   or an installer's environment, which may change on upgrade.
2. If `<vault>/skp` already exists, inspect it and reuse it if valid. Do not
   overwrite custom content or follow a broken link blindly. Also inspect each
   configured agent directory for an existing `skp` entry. A real directory or
   foreign symlink with that name blocks activation; keep it and report the
   conflict if it cannot be resolved without replacing user content.
3. For the fresh, empty config from step 3, run:

   ```sh
   skp add base skp
   skp use base --dry-run
   skp use base
   ```

   Inspect the preview before applying. It should only add the `skp` link in
   each configured directory, with no removals or conflicts.
4. For an existing active profile, retain that profile. Inspect
   `skp use <active-profile> --dry-run` for existing drift first. If it is clean
   and there are no `skp` collisions, run `skp add <active-profile> skp` if needed.
   **`add` applies immediately**, including inherited skills; it is not a staging
   command. Do not switch an existing installation to `base` just for setup.
   If no profile is active, inspect the existing profiles and managed links,
   select a profile that retains the user's skills, add `skp`, then preview and
   apply it. Ask only if the intended selection cannot be inferred.

Read `<vault>/skp/SKILL.md` now to learn how to handle subsequent requests. When
creating additional profiles later, include `skp` directly or through inheritance
so the agent can continue managing profiles.

## 5. Verify and report

```sh
skp --version
skp list --json
skp status --json
skp doctor
```

Verify that `doctor` exits successfully, the JSON reports no profile errors or
unmatched patterns, and `skp` appears in each configured agent's actual `linked`
list. `desired` alone does not prove that the links work. Check that existing
skills remain available. Foreign entries are expected when migration was skipped.
If a check fails, diagnose the reported paths and config; do not delete unrelated
entries or declare setup complete. Distinguish pre-existing issues from setup
failures and report any unresolved blocker.

Tell the user, in their language:

- The installed version, vault/config path, configured agent directories, and
  active profile.
- Whether verification passed and whether existing skills remain unmanaged.
- **Start a new agent session to load the skp skill.** Profile changes affect
  new sessions only; the current session does not hot-reload skills.
- They can now ask: “List my skill profiles”, “Switch to the writing profile”
  (if one exists), or “Enable this skill temporarily”. Equivalent commands are
  `skp list`, `skp use <profile>`, and `skp on <skill>`.

## Optional: migrate existing skills when requested

Inspect and back up the selected skill directories first. `skp adopt --all`
moves real skill directories into the vault and replaces them with links; it
does not import arbitrary external symlinks. New skills come from every configured
agent directory in configuration order. Identical copies become links; differing
copies stay in place and are reported.

Plan the destination profile before adoption. With an active profile, adoption
immediately reapplies it, so newly adopted skills absent from that profile can
lose their agent links. Preserve the intended enabled set in the profile before
adopting, or stage migration with no active profile. After adoption, add the
actual adopted names to the chosen profile, preview and apply it, then run
`skp status` and `skp doctor`. Do not switch to a profile containing only `skp`
after adopting all the user's skills. Report skipped or rejected skills;
successful earlier adoptions may remain even if a later one fails.