Registry & Publishing

Overview

spm registries store and distribute skill packages. You can use the public registry or host your own.

Publishing a skill

Prerequisites

1. Validate your skill:

spm validate ./my-skill

2. Authenticate with a registry:

# Via GitHub OAuth
spm login https://registry.example.com --github
 
# Or direct API token
spm login https://registry.example.com --name your-name

Publish

spm publish ./my-skill

The skill is packaged as a .tar.gz archive, hashed with SHA-256, uploaded to S3-compatible storage, and registered in the database.

Options:

# Publish to a specific registry
spm publish ./my-skill --registry my-registry
 
# Publish from a GitHub repository
spm publish https://github.com/user/repo --github
 
# Preview without executing
spm publish ./my-skill --dry-run
 
# Batch publish all skills in subdirectories
spm publish --all
spm publish --all --dry-run

Private packages

Private packages are only visible to their author. Other users cannot find, view, or install them.

To publish a private package, use the --private flag:

spm publish ./my-skill --private

Private packages require a paid plan:

You can manage your plan on the Account page.

Package limits

Each package has a maximum size of 50 KB. Packages exceeding this limit are rejected during publish.

The registry requires all published content to be verifiable. The following are not allowed and will be automatically rejected:

• Binary files
• Obfuscated code
• Dependencies with unrestricted shell permissions (shell:*) without justification

Update

Bump the version in SKILL.md frontmatter and publish again:

spm publish ./my-skill

The registry enforces version immutability — once a version is published, it cannot be overwritten. You must bump the version number to publish changes.

Installing from a registry

# Add latest version
spm add user/my-skill
 
# Add specific version
spm add user/my-skill --version 1.2.0

Dependencies are resolved automatically using semver ranges.

Managing registries

Add a registry

spm registry add https://registry.example.com --name my-registry

Options:

# With authentication token
spm registry add https://registry.example.com --token abc123
 

Self-hosting

You can run your own registry server. Requirements:

• Node.js 22+
• PostgreSQL for metadata storage
• S3-compatible storage for skill packages (AWS S3, Tigris, R2, MinIO)

Quick start

# Start the registry server
spm server start \
  --port 3717 \
  --database-url postgres://user:pass@localhost:5432/skills

Environment variables

Deploy with Docker

A Dockerfile and fly.toml are included in the repository for deploying to Fly.io or any container platform.

docker build -t spm-registry .
docker run -p 3717:3717 \
  -e DATABASE_URL=postgres://... \
  -e STORAGE_TYPE=s3 \
  -e S3_BUCKET=my-skills \
  spm-registry

API

The registry exposes:

• REST API — publish, download, search skills
• GraphQL API — programmatic queries for metadata, authors, versions
• GitHub integration — OAuth device flow, repo-based publishing

Security

Authentication

• API tokens — generated via spm login --name
• GitHub OAuth — device flow via spm login --github

Trust levels

Package integrity

Every published skill package includes a SHA-256 hash. spm verifies integrity on install.

Content safety

Every skill published to the official registry is automatically scanned for prompt injection patterns and other security threats. The scanning covers categories such as system prompt impersonation, instruction override attempts, data exfiltration, and privilege escalation.

Each skill receives a safety status:

Safety status is visible on each skill's page in the registry UI.

At runtime, skill content loaded into AI agents is wrapped with Microsoft Spotlighting delimiters — a technique that helps models distinguish between trusted instructions and untrusted skill data, reducing prompt injection risk.

The specific detection patterns and scoring logic are intentionally kept private to prevent adversarial evasion. Self-hosted registries can implement their own safety checks via the plugin system.

Runtime permission enforcement

Starting in v0.5.0, spm enforces skill permissions at runtime via Permission Proxy Tools. See the Security & Permissions guide for full details.