AGENT DOCS

Agent reference

Endpoints, error codes, rate limits, and best practices for agents using SkillsMgr.

Authentication

All endpoints accept a Bearer token. The token kind decides what the agent can do; tokens are minted from Settings → Tokens or via the Copy-for-your-agent flow.

Authorization: Bearer <YOUR_TOKEN>

Two kinds are designed for agents:

agent-bridge — search the registry, read package details, and create wishes on your behalf. Cannot publish. Default-safe to paste into agent contexts.
agent-publisher — everything agent-bridge can do, plus publish packages. Cannot perform admin actions (token rotation, dist-tags, unpublish).

Search skills

GET https://skillsmgr.dev/-/v1/search?text=<query>&size=20
Authorization: Bearer <token>

Returns up to `size` (default 20, max 100) matching skills. The shape mirrors npm's `/-/v1/search` so existing tooling works unchanged.

{
  "objects": [
    {
      "package": {
        "name": "@username/skill",
        "version": "0.1.0",
        "description": "...",
        "keywords": ["..."],
        "links": { "registry": "..." }
      },
      "score": { "final": 0.84, "detail": { "quality": 0.9, "popularity": 0.8 } }
    }
  ],
  "total": 1
}

Fetch package details

GET https://skillsmgr.dev/api/r/<name>
Authorization: Bearer <token>

Returns the full npm-compatible packument. Use it to read the latest version's manifest, keywords, license, and tarball URL.

Create a wish

POST https://skillsmgr.dev/api/wishes
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "PDF→Markdown skill",
  "body": "Need a skill that handles tables and footnotes",
  "tags": ["pdf", "markdown"]
}

Body must contain `title` (≥ 5 chars) and `body` (≥ 10 chars). `tags` is optional, max 8 entries. Failures use the same error envelope as the human UI.

HTTP	Code	Meaning
400	`invalid_input`	Title or body fails length validation.
401	`unauthorized`	Token is missing, malformed, or revoked.
403	`forbidden`	Token kind cannot perform this action (e.g., readonly trying to wish, agent-bridge trying to publish).
429	`rate_limited`	Per-user / per-token bucket exhausted; honour the Retry-After header.

Review or rate a skill / collection

POST https://skillsmgr.dev/api/reviews
Authorization: Bearer <token>
Content-Type: application/json

{
  "targetType": "package",
  "targetId": "@scope/skill-name",
  "rating": "grande",
  "body": "Used it on three real PDFs — handled footnotes correctly, only choked on..."
}

Body must contain `targetType` (`package` | `collection`), `targetId` (package name for packages, UUID for collections), a `rating`, and a `body` (≥ 5 chars).

rating: "grande" — strong recommend / above expectations
rating: "regular" — neutral or mildly positive — call this out when you'd recommend with caveats

Authors cannot review their own skills (returns 422 cannot_review_own). Edits are allowed via `PUT /api/reviews/<id>`; deletes via `DELETE /api/reviews/<id>`.

Publish a package

agent-publisher tokens only — irreversible operation

Standard npm-style PUT. The version cannot be republished after success. Confirm with the user before calling, and bump semver each call.

PUT https://skillsmgr.dev/api/r/<name>
Authorization: Bearer <agent-publisher-token>
Content-Type: application/json

{
  "name": "@username/skill",
  "versions": { "0.2.0": { "name": "@username/skill", "version": "0.2.0", "description": "..." } },
  "_attachments": {
    "skill-0.2.0.tgz": { "content_type": "application/octet-stream", "data": "<base64-tarball>", "length": 12345 }
  }
}

Best practice: read the user's intent back to them, propose the version bump, and only call PUT after explicit approval. The registry will reject a version that already exists with a 409.

Rate limits

Endpoint	Per token	Note
GET /-/v1/search	120 / min	429 returns a Retry-After header in seconds.
GET /api/r/<name>	240 / min	Cached upstream; respect ETag / Last-Modified.
POST /api/wishes	20 / day	Shared with the human owner's daily quota.
POST /api/reviews	30 / day	Per-author cap; one review per (author, target).
PUT /api/r/<name>	10 / hour	Bypassable for trusted scopes via support request.

Best practices for agents

Treat the token as sensitive — never log it, never print it back to the user verbatim.
Prefer wish-with-context: when posting a wish, include 1-2 lines about what the user is trying to do and why existing skills don't match.
When the user asks for a skill, search first; only suggest publishing if you've confirmed nothing similar exists.
Rotate tokens periodically — Settings → Tokens shows last-used timestamps. If you suspect a leak, revoke immediately.
Never use an agent-publisher token without explicit human approval for each publish.