skskills — Sovereign Agent Skills 🐧
Contents
- The 60-second version
- Quickstart
- What skskills provides
- Where it lives in SKStack v2
- A skill manifest
Skills your agent owns — install, run, and share capabilities like packages, with one MCP socket for the whole fleet. A skill is a self-describing bundle of knowledge, tools, and hooks; skskills installs them, namespaces them per agent, and proxies all of them through a single MCP server.
skskills is the skills platform/registry of the SKWorld
sovereign agent ecosystem — the MCP-native replacement for OpenClaw plugins. It
gives every capability the same shape (a skill.yaml manifest), the same
lifecycle (install → enable → load → run), and the same delivery channels (a
local path, a git repo, a pip package, or the curated catalog). Any
MCP-compatible agent — Claude Code, skcapstone, anything that speaks stdio MCP —
connects to one aggregator endpoint and sees every installed skill's tools.
The core idea: a skill declares what it provides (the three primitives
below); skskills resolves how — finds the entrypoint, namespaces the tool as
skill.tool, and serves it. You don't wire plugins into the agent; you install a
skill and the agent gains its tools.
The 60-second version
flowchart LR
SRC["a skill<br/>(path · git · pip · catalog)"] -->|"skskills install / pull / catalog install"| REG["local registry<br/>~/.skskills"]
REG -->|"per-agent + global namespaces"| LOAD["skskills run<br/>(aggregator)"]
LOAD -->|"resolve entrypoints"| SRV["one MCP server<br/>(stdio)"]
SRV -->|"skill.tool · skill://resource"| AGENT["any MCP agent<br/>(Claude Code · skcapstone)"]
Three primitives in every skill:
| Primitive | MCP shape | What it is |
|---|---|---|
| Knowledge | MCP resource (skill://name/path) |
context files (SKILL.md, references) the agent can read; can auto_load on start |
| Tool | MCP tool (skill.tool) |
an executable action — a Python dotpath/file (tools/x.py:run) or an executable script |
| Hook | lifecycle listener | event-driven script bound to on_boot, on_message_received, cron, … |
Quickstart
pip install -e . # into the ~/.skenv venv (project.scripts: skskills, skskills-aggregator)
skskills init my-skill --author "you" # scaffold knowledge/ tools/ hooks/ + a starter skill.yaml
skskills install ./my-skill # copy into the registry (global namespace)
skskills list # installed skills: version · agent · types · tools · signed
skskills run --agent lumina # start the aggregator MCP server on stdio for that agent
Pull from anywhere:
skskills catalog list # browse the curated first-party catalog (catalog.yaml)
skskills catalog install skseed # resolve pip/git coordinates and install
skskills pip-install skcapstone --agent lumina # install a skill bundled inside a pip package
skskills clone https://github.com/smilinTux/skmemory # install straight from a git repo
skskills pull skseal # download + install from the remote registry
Manage the fleet:
skskills info skseed # manifest detail: tools, knowledge, hooks, signature
skskills search logic # match installed skills by name / description / tag
skskills disable unhinged-mode # keep installed but stop exposing its tools
skskills link skseed lumina # symlink a global skill into an agent namespace
skskills package ./my-skill # build a distributable tarball (+ SHA-256, metadata sidecar)
skskills publish ./my-skill --token … # publish to the remote registry (CapAuth bearer)
skskills agents sync # link installed SKILL.md skills into every agent framework
skskills agents status # which frameworks can load each installed skill
Every global install that ships a SKILL.md is also symlinked, whole
directory, into each agent framework found on the machine, so it loads with no
extra step: ~/.claude/skills, $CODEX_HOME/skills (~/.codex),
~/.pi/agent/skills, ~/.hermes/skills/skskills, and ~/.config/opencode/skills
(OpenCode only when Claude Code is absent, because OpenCode already reads
~/.claude/skills). Uninstall removes the links. skskills only touches symlinks
that point into its own registry; a hand-made skill directory with the same name
is left alone and reported as a conflict. SKSKILLS_AGENT_LINKS=0 turns this off
(agent_links.py).
What skskills provides
| Piece | What it is |
|---|---|
skill.yaml manifest |
the Pydantic-validated skill schema: name, version, author, knowledge/tools/hooks, deps, and an optional CapAuth signature field that is currently stored and displayed but never verified (models.py) |
| Registry | local-first install/uninstall/enable/disable/search with per-agent + global namespaces under ~/.skskills/ (registry.py) |
| Loader | resolves each tool/hook entrypoint to a callable (dotpath, .py file, or executable script) and wraps the skill as a SkillServer (loader.py) |
| Aggregator | one MCP server that discovers all enabled skills and proxies their tools/resources; reports health + tool-name collisions (aggregator.py) |
| Catalog | the curated first-party skill list (catalog.yaml) with pip/npm/git coordinates and catalog install/info/search (catalog.py) |
| Remote | publish/download/pull over an HTTP registry, install from_git, package to a checksummed tarball (remote.py) |
| Pip bridge | find a skill.yaml bundled inside an installed pip package and register it — skills ship as ordinary Python packages (pip_bridge.py) |
| Agent links | symlink each installed SKILL.md skill into Claude Code, Codex, pi, Hermes, and OpenCode skill dirs; agents sync/status (agent_links.py) |
| CLI | skskills (Click + Rich) — the whole lifecycle from the terminal (cli.py) |
Delivery channels (all converge on the same registry install): local path · git repo · pip package · remote registry · curated catalog.
Discovery order at load time (agent overrides global): ~/.skskills/agents/<agent>/
→ ~/.skskills/installed/ → ~/.skcapstone/skills/ (skcapstone built-ins). The
fully-qualified skill.tool name always stays unique, so proxying is unambiguous;
base-name overlaps are reported via skskills.collisions.
Where it lives in SKStack v2
skskills is a Core capability — the capability-delivery layer for sovereign
agents. It is the platform primitive that turns the rest of the ecosystem (and any
third-party skill) into installable, namespaced, MCP-exposed tools. It is consumed
by skcapstone (which scans ~/.skcapstone/skills/ and uses the registry's
list_installed in its install wizard) and optionally verifies skill authenticity
through capauth.
flowchart TD
subgraph CORE["Core (identity · capabilities · governance)"]
SKSKILLS["**skskills**<br/>manifest · registry · loader · aggregator · catalog"]
CAPAUTH["capauth<br/>(PGP identity; signature verification<br/>is NOT yet implemented here)"]
SKCAP["skcapstone<br/>(agent runtime; ~/.skcapstone/skills built-ins)"]
end
subgraph CHANNELS["Skill delivery channels"]
LOCAL["local path"]
GIT["git repo"]
PIP["pip package<br/>(bundled skill.yaml)"]
CATALOG["curated catalog.yaml"]
REMOTE["remote registry<br/>skills.smilintux.org"]
end
subgraph AGENTS["MCP agents that consume skills"]
CC["Claude Code"]
OTHER["any stdio-MCP agent"]
end
LOCAL --> SKSKILLS
GIT --> SKSKILLS
PIP --> SKSKILLS
CATALOG --> SKSKILLS
REMOTE --> SKSKILLS
CAPAUTH -.->|"signature field only<br/>(unverified, see SECURITY.md)"| SKSKILLS
SKCAP -->|"list_installed · built-in skills"| SKSKILLS
SKSKILLS -->|"one aggregator MCP server (stdio)"| CC
SKSKILLS -->|"skill.tool · skill://resource"| OTHER
See docs/ARCHITECTURE.md for the install/load/serve lifecycle, the entrypoint-resolution rules, the namespace + collision model, and the full source map.
Docs index
| Doc | Read it for |
|---|---|
| SOP.md | The operational source of truth: build, test, release, the ten skill-discovery roots, the CLI and MCP reference, and a Symptom/Check troubleshooting table. Start here. |
| SECURITY.md | Threat model, reporting channel and 72h SLA, and the honest statement of what skskills does not verify. |
| CONTRIBUTING.md | Branch model, the real test gate (CI is not one), commit convention. |
| CHANGELOG.md | Release history, and why the version numbers here disagree with each other. |
| docs/DEPENDENTS.md | Who consumes skskills and how tightly. |
Maturity-tier: T0 (classical). skskills is not a crypto component: it performs no
key exchange and no signing, and uses SHA-256 only for tarball integrity. The
signature / signed_by manifest fields are stored and displayed but never
verified; see SECURITY.md before treating a "signed" skill as
trusted.
A skill manifest
name: my-skill
version: 0.1.0
description: What this skill does
author:
name: you
fingerprint: "" # CapAuth PGP fingerprint — enables signature verification
knowledge:
- path: knowledge/SKILL.md
description: Core knowledge for my-skill
auto_load: true
tools:
- name: greet
description: Say hello
entrypoint: tools/greet.py:run # dotpath, .py file, or executable script
input_schema: { type: object, properties: {}, required: [] }
hooks:
- event: on_boot
entrypoint: hooks/boot.py:main
tags: [sovereign]
skskills init scaffolds this for you; the loader resolves each entrypoint to a
callable and the aggregator serves my-skill.greet as an MCP tool and
skill://my-skill/knowledge/SKILL.md as an MCP resource.
"An agent without skills is just a chatbot. Skills are what make it sovereign."
Part of the SKWorld sovereign ecosystem · skills hub: skills.smilintux.org · 🐧 smilinTux
Metadata
Release files for skskills 1.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| skskills-1.2.1.tar.gz | 88.7 kB | Without provenance | Details for skskills-1.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| skskills-1.2.1-py3-none-any.whl | Python 3 | none | any | Details for skskills-1.2.1-py3-none-any.whl |
Total release size: 165.8 kB
Release files / skskills-1.2.1.tar.gz
| Download URL | skskills-1.2.1.tar.gz |
|---|---|
| Size | 88.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a156563f8f28f13d105fa90e0ab40c23e47b5c576bdcf03b76414a4afc86d9d1
|
|
BLAKE2b-256 checksum How to use checksums |
9cf54ca1db9d247f7cb1df2225751430149e49167972c2759822953d0934d1a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / skskills-1.2.1-py3-none-any.whl
| Download URL | skskills-1.2.1-py3-none-any.whl |
|---|---|
| Size | 77.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
801a05cd088c54cfb6941103c7ec427d798557758dd0643a75216110f410c938
|
|
BLAKE2b-256 checksum How to use checksums |
67fd5e0082492c318edaffa582f52c1c3151fb481c3a0f0b7e23626b5dcff1e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for skskills 1.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.