skp — skill profiles for AI coding agents

简体中文

skp manages skills for AI coding agents. It organizes skills into profiles, so multiple agents can share one skill library and switch skill sets together. Profiles let you enable the skills you need and reduce unrelated skill descriptions in the agent's context.

Use skp with agents that discover skills through directories. Switches apply to new sessions. Unmanaged skills and plugin caches remain outside skp's control.

1. Install

Requires Python 3.11 or later and a POSIX system with symlink support.

pipx install skp
# Or: uv tool install skp

To install through your agent, send it the installation guide or this prompt:

Read https://raw.githubusercontent.com/ni00/skp/main/INSTALL.md and follow it to install and configure skp, preserve access to my existing skills, and verify the setup.

For a source installation, run uv tool install . from this repository.

2. Get started

1. Initialize the configuration:

   skp init

   init creates an empty base profile without overwriting existing config. Review agent_dirs in ~/.skills-vault/profiles.toml before migrating skills.

2. Move existing skills into the vault:

   skp adopt --all
   skp status

   adopt moves real skill directories and replaces them with symlinks. Each skill must contain SKILL.md. External symlinks are not imported.

3. Add skills to a profile and activate it. Replace anysearch with a skill listed by skp status:

   skp add base anysearch
   skp use base
   skp doctor

4. Start a new agent session to load the selected skills.

3. Configure profiles

The vault stores skills and configuration. Selected skills are symlinked into each agent's skill directory:

~/.skills-vault/
├── profiles.toml        # Profile definitions and agent directories
├── state.json           # Active profile and extra skill patterns (overlay)
├── installed.toml       # Origins of installed skills (written by install)
└── anysearch/
    └── SKILL.md

~/.agents/skills/
└── anysearch -> ~/.skills-vault/anysearch

Define profiles in ~/.skills-vault/profiles.toml, using names and patterns that match your vault:

agent_dirs = ["~/.agents/skills", "~/.codex/skills"]

[profiles.base]
description = "Everyday tools"
skills = ["anysearch"]

[profiles.writing]
description = "Writing and documentation"
inherit = ["base"]
skills = ["draft-*", "*-review"]

[profiles.research]
description = "Literature and web research"
inherit = ["base"]
skills = ["paper-*", "citation-*"]

skills accepts skill directory names and glob patterns such as draft-*. inherit includes other profiles' skills and supports multiple levels. Profiles must explicitly inherit base to include its skills.

After editing the file, preview and apply a profile:

skp use writing --dry-run
skp use writing

To edit profiles from the CLI:

skp create review
skp add review 'draft-*' '*-review'
skp rm review 'draft-*'

Quote globs to prevent shell expansion. rm removes the exact stored pattern; it does not exclude skills matched by another pattern or inherited profile. add and rm reapply the active profile, if one is selected.

Set SKP_HOME to use a different vault. Relative agent_dirs paths are resolved from the directory containing profiles.toml. Agent directories must not overlap one another or the vault.

3.1 Add extra skills

An overlay adds skills without changing the profile definition:

skp on 'paper-*'
skp off 'paper-*'

Overlays persist across profile switches. off removes the exact pattern passed to on, leaving skills included by the profile enabled. To switch and clear the overlay:

skp use writing --clear-overlay

3.2 Add agent directories

skp scan                 # Discover user skill directories
skp scan --register      # Add discovered directories to agent_dirs

Registration does not move skills or change links. Add any directories missed by the scan to agent_dirs manually.

To migrate skills from registered directories, run skp adopt --all. If a profile is active, add skills you want to keep enabled to it first: adopt reapplies that profile after migration.

4. Install skills from repositories

skp install copies skills into the vault from a GitHub repository, another git URL, or a local directory. A source must provide a SKILL.md entry point — at its root, in skills/ subdirectories, or as top-level directories:

skp install owner/repo                     # GitHub shorthand, default branch
skp install owner/repo@v1.2                # Pinned ref
skp install https://github.com/owner/repo
skp install ./my-skills                    # Local directory
skp install owner/repo --skill anysearch --into base

Each installed skill's origin is recorded in the vault manifest (installed.toml), so skills can be refreshed and removed cleanly:

skp update                       # Refresh installed skills from their sources
skp update anysearch --dry-run   # Preview what would change
skp uninstall anysearch          # Remove from the vault

install skips identical content and requires --force to replace a vault copy that differs. Git sources are shallow-cloned, so update re-fetches from the network; local sources are reported and skipped by update. uninstall only removes manifest-tracked skills and refuses skills the active profile or overlay still references.

skp coexists with other skill installers (for example the skills.sh CLI, which also keeps a canonical copy in ~/.agents/skills). It never deletes their directories: if such a tool replaces an adopted skill's link with its own copy, switching aborts with a conflict, and skp adopt --all re-links an identical copy while keeping differing copies until you resolve them. To avoid fights over the same skill, let one tool own each skill name.

5. Set a project default

Select a profile, then save its name in the current directory's .skp file:

skp use writing
skp save

skp save ./my-project targets another existing directory. It saves the profile name, not its skill definitions or overlay, and preserves existing allowed profiles.

To allow more than one profile, edit .skp:

profiles = ["writing", "research"]
default = "writing"

From the project or any subdirectory:

skp use                  # Apply the default profile
skp use research         # Select another allowed profile

The nearest .skp applies. profiles lists allowed profiles; default is optional and must name one of them. Overlay skills must belong to an allowed profile, including inherited skills. Use --clear-overlay to remove extras that conflict with this restriction.

The active profile and agent links are shared across your user account. .skp restricts commands run in the project; switching also affects new sessions in other projects. Entering a directory does not switch profiles automatically.

6. Inspect and troubleshoot

Command	Use it to
skp list	List profiles, skill counts, inheritance, and project restrictions
skp status	Inspect the active profile, overlay, and actual agent links
skp doctor	Check configuration and links; exit with code 1 if problems exist
skp use <profile> --dry-run	Preview link changes and conflicts without writing
skp help [command]	Show general or command-specific help

scan, list, and status support --json. In status, desired lists intended skills; each agent's linked list reports actual valid links.

For link errors or interrupted operations, inspect skp status, resolve reported issues, and reapply the profile. Patterns that match no skills produce warnings during switching and failures in doctor.

7. Install the agent skill

The bundled skp skill teaches your agent how to manage profiles. To install it manually:

1. Run skp skill to print its directory. This command only reports the path.
2. Copy that entire directory into the vault as skp. With the default vault, the entry point must be ~/.skills-vault/skp/SKILL.md. If skp already exists, compare the contents before replacing it. For a source checkout, copy skills/skp.
3. Add the skill to a profile, for example, skp add base skp.

Activate that profile and start a new agent session to load the instructions.

8. Contribute

See CONTRIBUTING.md for development setup, checks, and design constraints.

9. License

MIT