Documentation | SkillsMgr

Introduction

SkillsMgr is the package registry for AI agent skills. Browse, share, and install reusable skills that work across Claude Code, Codex, and other AI agents.

Quick Start

# Install a skill
skillsmgr install code-review

# Publish your skill
skillsmgr publish

Installation

SkillsMgr CLI can be installed via npm:

npm install -g skillsmgr

Or use the API directly — no CLI needed.

skill.json Reference

{
  "name": "my-skill",
  "version": "1.0.0",
  "description": "What this skill does",
  "main": "SKILL.md",
  "keywords": ["tag1", "tag2"],
  "author": "username",
  "license": "MIT",
  "engines": {
    "claude-code": ">=1.0.0",
    "codex": ">=1.0.0"
  },
  "dependencies": {
    "base-prompts": "^1.0.0"
  }
}

Field	Required	Description
`name`	Yes	Lowercase, hyphens, dots. Scoped: @scope/name
`version`	Yes	Semantic versioning (major.minor.patch)
`description`	Yes	Short description
`main`	No	Entry point file (default: skill.md)
`keywords`	No	Search tags
`author`	No	Author name
`license`	No	SPDX license (default: MIT)
`engines`	No	Compatible AI agents
`dependencies`	No	Other skills this depends on

Publishing a Skill

Create a skill.json in your skill directory
Write your skill file (SKILL.md or skill.md)
Register an account on SkillsMgr
Get your API token from Dashboard
skillsmgr publish or use the API:

curl -X PUT https://skillsmgr.dev/my-skill \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "description": "My awesome skill",
    "manifest": {
      "name": "my-skill",
      "version": "1.0.0",
      "description": "My awesome skill",
      "keywords": ["ai", "tool"],
      "author": "username",
      "license": "MIT"
    },
    "tarball": "base64-encoded-tarball..."
  }'

Note: If no README is provided in the manifest, one will be auto-generated from the package metadata.

Note: The publish format above is SkillsMgr-specific. While the API paths follow npm conventions, the request body uses a simplified format with base64-encoded tarball.

Versioning

Follow semver: MAJOR.MINOR.PATCH

MAJOR — Breaking changes
MINOR — New features, backward compatible
PATCH — Bug fixes

API Reference — Authentication

All write operations require a Bearer token:

Authorization: Bearer spm_xxxxx

Get your token from Dashboard → API Token section.

API Reference — Packages

`GET /:name` — Get package metadata (npm packument format)

curl https://skillsmgr.dev/code-review

{
  "_id": "code-review",
  "name": "code-review",
  "description": "AI-powered code review",
  "dist-tags": { "latest": "1.0.0" },
  "versions": {
    "1.0.0": {
      "name": "code-review",
      "version": "1.0.0",
      "dist": {
        "tarball": "https://skillsmgr.dev/code-review/-/code-review-1.0.0.tgz",
        "integrity": "sha512-...",
        "shasum": "abc123..."
      }
    }
  },
  "time": {
    "created": "2026-03-26T09:45:30.123Z",
    "modified": "2026-03-26T09:45:30.123Z",
    "1.0.0": "2026-03-26T09:45:30.123Z"
  },
  "maintainers": [{ "name": "testuser" }]
}

`GET /:name/:version` — Get specific version

curl https://skillsmgr.dev/code-review/1.0.0

`PUT /:name` — Publish a new version (requires auth)

curl -X PUT https://skillsmgr.dev/my-skill \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0.0",
    "description": "My awesome skill",
    "manifest": {
      "name": "my-skill",
      "version": "1.0.0",
      "description": "My awesome skill",
      "keywords": ["ai", "tool"],
      "author": "username",
      "license": "MIT"
    },
    "tarball": "base64-encoded-tarball..."
  }'

Response (201):

{ "ok": true, "id": "uuid", "version": "1.0.0", "integrity": "sha512-..." }

Error responses:

401: Missing or invalid Authorization header
409: Version already exists for this package
403: You do not have permission to publish to this package

`GET /:name/stats` — Download statistics

curl https://skillsmgr.dev/code-review/stats

{ "total": 42, "weekly": 12, "daily": 3 }

`GET /:name/-/:filename` — Download tarball

curl -O https://skillsmgr.dev/code-review/-/code-review-1.0.0.tgz

API Reference — Search

`GET /-/v1/search` — npm-compatible search endpoint

This endpoint follows the npm registry search protocol.

# Search by keyword
curl "https://skillsmgr.dev/-/v1/search?text=code&size=5"

# List all packages
curl "https://skillsmgr.dev/-/v1/search?text=&from=0&size=20"

Query parameters:

Param	Default	Description
`text`	(required)	Search query (required, empty string returns all)
`from`	`0`	Pagination offset
`size`	`20`	Results per page (max 250)

`GET /api/search` — Web search endpoint (unchanged)

The web frontend continues to use this endpoint.

curl "https://skillsmgr.dev/api/search?q=code&limit=5&sort=downloads"

Param	Default	Description
`q`	(required)	Search query (empty string returns all)
`offset`	`0`	Pagination offset
`limit`	`20`	Results per page (max 100)
`sort`	`relevance`	Sort: relevance, downloads, recent

API Reference — Whoami

Returns the authenticated user. Requires Bearer token.

`GET /-/whoami`

curl https://skillsmgr.dev/-/whoami \
  -H "Authorization: Bearer spm_xxxxx"

{ "username": "testuser" }

API Reference — Dist Tags

`GET /-/package/:name/dist-tags` — Get all dist-tags for a package

curl https://skillsmgr.dev/-/package/code-review/dist-tags

{ "latest": "1.0.0" }

`PUT /-/package/:name/dist-tags/:tag` — Set a dist-tag (requires auth)

curl -X PUT https://skillsmgr.dev/-/package/code-review/dist-tags/beta \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"2.0.0-beta.1"'

`DELETE /-/package/:name/dist-tags/:tag` — Delete a dist-tag (requires auth, cannot delete "latest")

curl -X DELETE https://skillsmgr.dev/-/package/code-review/dist-tags/beta \
  -H "Authorization: Bearer YOUR_TOKEN"

API Reference — Token Management

`GET /-/npm/v1/tokens` — List all tokens for the authenticated user

curl https://skillsmgr.dev/-/npm/v1/tokens \
  -H "Authorization: Bearer spm_xxxxx"

`POST /-/npm/v1/tokens` — Create a new token

curl -X POST https://skillsmgr.dev/-/npm/v1/tokens \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "password": "your-password" }'

`DELETE /-/npm/v1/tokens/token/:key` — Delete a token by key

curl -X DELETE https://skillsmgr.dev/-/npm/v1/tokens/token/abc123 \
  -H "Authorization: Bearer spm_xxxxx"

API Reference — Users

GET /api/users/:username — Get user profile and published skills

curl https://skillsmgr.dev/api/users/testuser

{
  "username": "testuser",
  "avatarUrl": null,
  "bio": null,
  "packages": [
    {
      "name": "code-review",
      "description": "AI-powered code review",
      "version": "1.0.0",
      "downloads": 2
    }
  ]
}

API Reference — Auth

# Start GitHub OAuth flow (redirects browser)
GET /api/auth/github

# Register with email/password
curl -X POST https://skillsmgr.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "myuser", "email": "me@example.com", "password": "securepass"}'

# Login
curl -X POST https://skillsmgr.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "me@example.com", "password": "securepass"}'

`PUT /-/user/org.couchdb.user::username` — npm-compatible login/register

This endpoint is used by the npm/spm CLI for authentication.

curl -X PUT https://skillsmgr.dev/-/user/org.couchdb.user:myuser \
  -H "Content-Type: application/json" \
  -d '{"name": "myuser", "password": "securepass"}'

{ "ok": true, "id": "org.couchdb.user:myuser", "token": "spm_..." }

Agent Compatibility

SkillsMgr skills work with multiple AI agents. Declare compatibility in engines:

Agent	Directory	Auto-detected by
Claude Code	`.claude/commands/`	.claude/ directory
Codex	`.codex/`	codex.md file

When installing via CLI, skills are automatically linked to the detected agent's directory.

Permissions Coming Soon

Skills will declare required permissions in skill.json:

{
  "permissions": {
    "tools": ["Read", "Write"],
    "paths": ["src/**"],
    "network": ["api.github.com"]
  }
}

Dependencies Coming Soon

Skills can depend on other skills:

{
  "dependencies": {
    "base-prompts": "^1.0.0"
  }
}

Introduction

Quick Start

Installation

skill.json Reference

Publishing a Skill

Versioning

API Reference — Authentication

API Reference — Packages

GET /:name — Get package metadata (npm packument format)

GET /:name/:version — Get specific version

PUT /:name — Publish a new version (requires auth)

GET /:name/stats — Download statistics

GET /:name/-/:filename — Download tarball