DOCS

Documentation

Everything you need to publish, install, and share AI skills

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.

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

bash

# Add a skill
npx skillsmgr add code-review

# Publish your skill
npx skillsmgr publish

Installation

SkillsMgr CLI can be installed via npm:

bash

npm install -g skillsmgr

Or use the API directly — no CLI needed.

skill.json Reference

skill.json

{
  "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
npx skillsmgr publish or use the API:

bash

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:

header

Authorization: Bearer spm_xxxxx

Get your token from Dashboard → API Token section.

CLI Browser Login

The CLI can authenticate via a browser-based login flow, supporting all auth methods (email/password, GitHub OAuth, etc).

Flow

CLI generates a random session ID and opens {registry}/cli-auth?session={id} in the browser
User logs in on the web page
CLI polls GET /api/cli-auth/poll?session={id} every 2 seconds
On success, the poll returns an API token

`GET /api/cli-auth/poll?session={id}`

json

// Pending — user hasn't logged in yet
{ "status": "pending" }

// Complete — token returned (only once)
{ "status": "complete", "token": "spm_xxx", "username": "xxx" }

// Consumed — token already retrieved
{ "status": "consumed" }

// Expired — session timed out (5 minutes)
{ "status": "expired" }

`POST /api/cli-auth/token`

Alternative to polling. Exchange session ID for token:

bash

curl -X POST https://skillsmgr.dev/api/cli-auth/token \
  -H "Content-Type: application/json" \
  -d '{"session_id": "your-session-id"}'

API Reference — Packages

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

bash

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

json

{
  "_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

bash

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

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

bash

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):

json

{ "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

bash

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

json

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

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

bash

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.

bash

# 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.

bash

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`

bash

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

json

{ "username": "testuser" }

API Reference — Dist Tags

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

bash

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

json

{ "latest": "1.0.0" }

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

bash

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")

bash

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

bash

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

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

bash

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

bash

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

bash

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

json

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

API Reference — Auth

bash

# 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/skillsmgr CLI for authentication.

bash

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

json

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

Collections · Collections

Collections group related skills under @scope/slug URLs. Owners can add or remove members, pin versions, reorder, and star other collections. Public reads are anonymous; mutations require a Bearer token.

`GET /api/collections?mine=true` — list your collections

bash

curl https://skillsmgr.dev/api/collections?mine=true \
  -H "Authorization: Bearer spm_xxxxx"

Pass contains=<package> to additionally flag collections that already contain a given skill — used by the "Add to collection" popover on skill detail pages.

`POST /api/collections` — create

bash

curl -X POST https://skillsmgr.dev/api/collections \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "frontend-helpers",
    "name": "Frontend Helpers",
    "description": "My favourite UI skills"
  }'

`GET /api/collections/:scope/:slug` — fetch

:scope is @username; :slug is the collection slug. Returns metadata, members, star count, and viewer state (viewerIsOwner, viewerHasStarred).

bash

curl https://skillsmgr.dev/api/collections/@alice/frontend-helpers

`PATCH /api/collections/:scope/:slug` — update

Owner-only. Body fields are all optional.

bash

curl -X PATCH https://skillsmgr.dev/api/collections/@alice/frontend-helpers \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Frontend Helpers v2",
    "description": "Updated description",
    "slug": "frontend-helpers"
  }'

`POST /api/collections/:scope/:slug/members` — add member

bash

curl -X POST https://skillsmgr.dev/api/collections/@alice/frontend-helpers/members \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "code-review",
    "pinnedVersion": "1.0.0"
  }'

pinnedVersion is optional — when omitted the member tracks the package's latest dist-tag.

`PATCH /api/collections/:scope/:slug/members` — reorder

Atomic reorder of all members in one call.

bash

curl -X PATCH https://skillsmgr.dev/api/collections/@alice/frontend-helpers/members \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "order": [
      { "packageName": "code-review", "position": 0 },
      { "packageName": "lint-rules", "position": 1 }
    ]
  }'

`DELETE /api/collections/:scope/:slug/members/:pkg` — remove

:pkg is the URL-encoded package name. Use PATCH on the same path to update its pinnedVersion.

`POST | DELETE /api/collections/:scope/:slug/star` — star toggle

bash

# Star
curl -X POST https://skillsmgr.dev/api/collections/@alice/frontend-helpers/star \
  -H "Authorization: Bearer spm_xxxxx"

# Unstar
curl -X DELETE https://skillsmgr.dev/api/collections/@alice/frontend-helpers/star \
  -H "Authorization: Bearer spm_xxxxx"

`GET /api/collections/search?q=&limit=` — full-text

ILIKE-based search over slug / name / description. Returns collections with hydrated memberCount and a few member sketches for card previews.

bash

curl "https://skillsmgr.dev/api/collections/search?q=frontend&limit=20"

Other endpoints

POST /api/collections/:scope/:slug/fork — fork into your account
GET /api/collections/:scope/:slug/used-by — installs that include this collection
POST /api/collections/:scope/:slug/transfer + /transfer/accept — transfer ownership
POST /api/collections/:scope/:slug/unpublish — soft-unpublish (owner-only)
POST /api/collections/resolve — resolve @scope/slug to ID + member skill names

Reviews & Ratings · Reviews & Ratings

Reviews live on package and collection targets. Each user has at most one review per target. Therating field is binary: regular (small cup) or grande (large cup). Reviews can collect helpful / unhelpful votes and threaded replies.

`GET /api/reviews?targetType=&targetId=` — list reviews

Required query: targetType (package | collection) and targetId (package name for packages; collection UUID for collections). Optional:sort=helpfulness|newest, limit (default 20, max 100), cursor, includeReplies=true.

bash

curl "https://skillsmgr.dev/api/reviews?targetType=package&targetId=code-review&sort=helpfulness&includeReplies=true"

`POST /api/reviews` — create or update

One review per (author, target) — re-posting overwrites the previous content. Bearer token required.

bash

curl -X POST https://skillsmgr.dev/api/reviews \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "package",
    "targetId": "code-review",
    "rating": "grande",
    "body": "Saved me hours on legacy PRs."
  }'

`GET | PATCH | DELETE /api/reviews/:id`

Fetch single review, edit body / rating (author-only, until votes arrive), or soft-delete. Deleted reviews remain in/api/reviews/mine with deletedAt set.

`POST /api/reviews/:id/vote` — helpful / unhelpful

bash

curl -X POST https://skillsmgr.dev/api/reviews/REVIEW_ID/vote \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "value": "helpful" }'

Pass { "value": null } to clear an existing vote. Authors cannot vote on their own reviews.

`POST /api/reviews/:id/replies` — reply

bash

curl -X POST https://skillsmgr.dev/api/reviews/REVIEW_ID/replies \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Glad it helped!" }'

Manage replies via PATCH | DELETE /api/reviews/replies/:id and flag abusive replies via POST /api/reviews/replies/:id/flag.

`POST /api/reviews/:id/flag` — flag a review

bash

curl -X POST https://skillsmgr.dev/api/reviews/REVIEW_ID/flag \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "spam" }'

Reasons: spam | adult | abuse | fake | other. Reviews that pass an internal threshold transition tomoderationStatus: "hidden_by_system".

`GET /api/reviews/mine` — your authored reviews

Includes deleted ones so the dashboard can show "Show deleted". Items contain targetId verbatim — for collection targets, the dashboard hydrates the slug separately to build navigable links.

Wishpool · Wishpool

The wishpool is the public requests board at /wishes. Anyone can read; logged-in users can create wishes, vote, propose a fulfilment (an existing skill or collection), and confirm / reject incoming proposals.

`GET /api/wishes?status=&sort=&limit=&cursor=`

status: all | open | fulfilled (default all). sort: hot | new | old (default hot). Anonymous reads work; pass a Bearer token if you also want votedByMe hydrated.

bash

curl "https://skillsmgr.dev/api/wishes?status=open&sort=hot&limit=20"

`POST /api/wishes` — create wish

bash

curl -X POST https://skillsmgr.dev/api/wishes \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "A skill that audits Tailwind for unused classes",
    "body": "...details / context...",
    "tags": ["frontend", "tailwind"]
  }'

`GET | PATCH | DELETE /api/wishes/:id`

Fetch one wish; requester can edit title / body / tags or soft-delete. Deletion is final — vote count and proposals collapse.

`POST /api/wishes/:id/vote` — toggle vote

Idempotent toggle. Authors cannot vote on their own wishes. Body: { "on": true | false }.

bash

curl -X POST https://skillsmgr.dev/api/wishes/WISH_ID/vote \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "on": true }'

`POST /api/wishes/:id/propose` — propose fulfilment

Suggest an existing skill or collection that satisfies this wish. The wish requester then confirms or rejects.

bash

# Propose a package
curl -X POST https://skillsmgr.dev/api/wishes/WISH_ID/propose \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "kind": "package", "packageName": "tailwind-auditor" }
  }'

# Propose a collection
curl -X POST https://skillsmgr.dev/api/wishes/WISH_ID/propose \
  -H "Authorization: Bearer spm_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "kind": "collection",
      "ownerUsername": "alice",
      "slug": "frontend-helpers"
    }
  }'

`POST /api/wishes/:id/confirm` · `/reject`

Requester-only. confirm flips the wish to fulfilled and freezes the proposed target into thefulfilled field. reject drops the current proposal and returns the wish to open.

bash

curl -X POST https://skillsmgr.dev/api/wishes/WISH_ID/confirm \
  -H "Authorization: Bearer spm_xxxxx"

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:

skill.json

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

Dependencies

Skills can depend on other skills:

skill.json

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

Documentation

Introduction

Quick Start

Installation

skill.json Reference

Publishing a Skill

Versioning

API Reference — Authentication

CLI Browser Login

Flow

GET /api/cli-auth/poll?session={id}

POST /api/cli-auth/token

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

API Reference — Search

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

Query parameters:

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

API Reference — Whoami

GET /-/whoami

API Reference — Dist Tags

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

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

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

API Reference — Token Management

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

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

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

API Reference — Users

API Reference — Auth

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

Collections · Collections

GET /api/collections?mine=true — list your collections

POST /api/collections — create

GET /api/collections/:scope/:slug — fetch

PATCH /api/collections/:scope/:slug — update

POST /api/collections/:scope/:slug/members — add member

PATCH /api/collections/:scope/:slug/members — reorder

DELETE /api/collections/:scope/:slug/members/:pkg — remove

POST | DELETE /api/collections/:scope/:slug/star — star toggle

GET /api/collections/search?q=&limit= — full-text

Other endpoints

Reviews & Ratings · Reviews & Ratings

GET /api/reviews?targetType=&targetId= — list reviews

POST /api/reviews — create or update

GET | PATCH | DELETE /api/reviews/:id

POST /api/reviews/:id/vote — helpful / unhelpful

POST /api/reviews/:id/replies — reply

POST /api/reviews/:id/flag — flag a review

GET /api/reviews/mine — your authored reviews

Wishpool · Wishpool

GET /api/wishes?status=&sort=&limit=&cursor=

POST /api/wishes — create wish

GET | PATCH | DELETE /api/wishes/:id

POST /api/wishes/:id/vote — toggle vote

POST /api/wishes/:id/propose — propose fulfilment

POST /api/wishes/:id/confirm · /reject

Agent Compatibility

Permissions · Coming Soon

Dependencies

`GET /api/cli-auth/poll?session={id}`

`POST /api/cli-auth/token`

`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

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

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

`GET /-/whoami`

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

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

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

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

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

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

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

`GET /api/collections?mine=true` — list your collections

`POST /api/collections` — create

`GET /api/collections/:scope/:slug` — fetch

`PATCH /api/collections/:scope/:slug` — update

`POST /api/collections/:scope/:slug/members` — add member

`PATCH /api/collections/:scope/:slug/members` — reorder

`DELETE /api/collections/:scope/:slug/members/:pkg` — remove

`POST | DELETE /api/collections/:scope/:slug/star` — star toggle

`GET /api/collections/search?q=&limit=` — full-text

`GET /api/reviews?targetType=&targetId=` — list reviews

`POST /api/reviews` — create or update

`GET | PATCH | DELETE /api/reviews/:id`

`POST /api/reviews/:id/vote` — helpful / unhelpful

`POST /api/reviews/:id/replies` — reply

`POST /api/reviews/:id/flag` — flag a review

`GET /api/reviews/mine` — your authored reviews

`GET /api/wishes?status=&sort=&limit=&cursor=`

`POST /api/wishes` — create wish

`GET | PATCH | DELETE /api/wishes/:id`

`POST /api/wishes/:id/vote` — toggle vote

`POST /api/wishes/:id/propose` — propose fulfilment

`POST /api/wishes/:id/confirm` · `/reject`