# spm (Skills Package Manager)

> npm for AI skills — create, share, and discover reusable AI instructions that work with any model via MCP (Model Context Protocol).

spm is an open, model-agnostic AI skill ecosystem. Skills are NOT code — they are structured instructions (SKILL.md + skill.json) that AI models load into their context to perform specific tasks.

## Key Concepts

- **Skill**: A directory with skill.json (manifest) + SKILL.md (instructions for the AI model)
- **MCP**: Model Context Protocol — the transport layer between AI clients and spm
- **Registry**: A server (PostgreSQL + S3) that stores and distributes skill packages
- **Lazy Loading**: Skills load on demand — the model reads a compact index and pulls in what it needs
- **Confidence**: A 0.0-1.0 score computed from usage feedback, used to rank skill quality

## CLI

The command-line tool is `spm` (Skills Package Manager).

Core commands: init, create, validate, install, uninstall, list, info, search, rate, stats
Publishing: publish, update, login, registry add
Integration: connect, disconnect, serve, protocol-handle, protocol register/unregister
Personas: persona create/list/activate/deactivate/info/remove/validate/export/deploy/import
System: status-server start/stop/status, connections list/test/default/remove, migrate detect/run
Advanced: convert, reindex

## Personas

Personas are `.person.json` files that define AI agent personalities — role, tone, guidelines, and curated skill sets. When activated, persona character instructions are injected into the MCP server automatically.

- **Format**: `.person.json` with schema_version, name, version, description, author, license, character (role, tone, guidelines, instructions), skills (semver deps), settings (temperature, top_p)
- **Storage**: `~/.skills/personas/` (global), `.skills/personas/` (project, overrides global)
- **CLI**: `spm persona create/list/activate/deactivate/info/remove/validate/export/deploy/import`
- **Deploy**: Export personas to external AI platforms (e.g. OpenClaw) with `spm persona export/deploy`
- **MCP tools**: `persona_list`, `persona_load`
- **Chat**: mention with `@persona-name` to load on demand

## MCP Tools (exposed to AI models)

- skill_list — compact index of all installed skills
- skill_load — load full skill instructions into context
- skill_context — current session state (loaded skills, token budget)
- skill_search — search local and remote skills
- skill_feedback — record usage results (success/partial/failure/false_trigger)
- skill_install — install a skill from registry (requires user approval)
- persona_list — list available personas
- persona_load — load persona character and skills

## Docs

- [Getting Started](https://skillbase.space/docs/getting-started): Install spm and load your first skill
- [Creating Skills](https://skillbase.space/docs/creating-skills): Write skill.json + SKILL.md
- [skill.json Spec](https://skillbase.space/docs/skill-json-spec): Full manifest schema reference
- [CLI Reference](https://skillbase.space/docs/cli-reference): All spm commands
- [MCP Integration](https://skillbase.space/docs/mcp-integration): Connect to 14 AI clients via MCP
- [Personas](https://skillbase.space/docs/personas): Define AI agent personalities with roles, tone, and skills
- [Deploy Targets](https://skillbase.space/docs/deploy-targets): Export and deploy personas to OpenClaw and other platforms
- [Registry & Publishing](https://skillbase.space/docs/registry): Publish and self-host registries
- [Self-Hosting](https://skillbase.space/docs/self-hosting): Run your own private registry server

## Full Documentation

For complete documentation in a single file (AI-optimized):
- [llms-full.txt](https://skillbase.space/llms-full.txt)