Skills API¶

Base URL: /api/v1

Authentication¶

The Skills API uses dual authentication — the auth method depends on the endpoint:

Sync-down reads accept Bearer tokens so that CLI agents can pull skill content using managed-agent tokens without a browser session. Write endpoints are session-only to prevent proxy token replay.

Content type: Content-Type: application/json

Access Control¶

Skills use the same ACL system as MCP Servers and A2A Agents:

• Resource type: skill (in RegistryResourceType enum)
• Permission bits: VIEW (1), EDIT (3), DELETE / OWNER (15)
• Seed roles: skill_viewer (permBits=1), skill_editor (permBits=3), skill_owner (permBits=15)
• On create: the author is automatically granted OWNER permission (atomic transaction)
• On delete: all ACL entries for the skill are removed (atomic transaction)

List endpoints return only skills the user has VIEW access to. Individual operations check the required permission level (VIEW for reads, EDIT for updates/toggle, DELETE for deletion).

Data Sharing with Jarvis Chat¶

Skills and SkillFiles are stored in shared MongoDB collections (skills, skillfiles). Registry uses Beanie's use_state_management = True so that save() emits incremental $set updates, preserving Chat-only fields that are not modelled on ExtendedSkill.

Key distinctions:

Endpoints¶

1. List Skills¶

GET /skills

Returns metadata for all skills the authenticated user has VIEW access to, ordered by updatedAt ascending.

Query Parameters¶

Request Example¶

GET /api/v1/skills?enabled=true&fileCount=0
Authorization: Bearer <token>
Accept: application/json

Response¶

200 OK

{
  "skills": [
    {
      "id": "<skill-objectid>",
      "name": "mongoose-to-beanie",
      "displayTitle": "Mongoose to Beanie",
      "description": "Convert Mongoose schemas to Beanie models",
      "category": "development",
      "tags": ["python", "mongodb"],
      "path": "mongoose-to-beanie",
      "version": 3,
      "fileCount": 0,
      "alwaysApply": false,
      "enabled": true,
      "author": "<user-objectid>",
      "authorName": "Jane Doe",
      "source": "inline",
      "sourceMetadata": null,
      "createdByRegistry": true,
      "permissions": {
        "VIEW": true,
        "EDIT": true,
        "DELETE": true,
        "SHARE": true
      },
      "updatedAt": "2026-08-05T10:01:00Z",
      "deletedAt": null
    }
  ]
}

Response Fields¶

2. Create Skill¶

POST /skills

Creates a new skill. The authenticated user is automatically granted OWNER permission. A duplicate check is performed on (name, author) — returns 409 on conflict.

Request Body¶

SkillFileInput¶

Server-enforced limits (all return 422 on breach): - Single file: 5 MiB (MAX_SKILL_FILE_SIZE), applied to the decoded byte count. - Total per skill: 10 MiB (MAX_SKILL_FILES_TOTAL_SIZE). - Count per skill: 50 (MAX_SKILL_FILE_COUNT). - Duplicate relativePath within a single request is rejected.

Wire size note. Binary payloads travel as base64 in JSON, which expands the raw bytes by ~1.33×. A single 5 MiB binary is therefore ~6.7 MiB on the wire, and a full 10 MiB skill can approach ~13.3 MiB of JSON body. Front-facing proxies (nginx client_max_body_size, ALB request-size limits, API gateway caps) must allow at least this much or clients will receive 413 Payload Too Large instead of Registry's 422.

Request Example¶

POST /api/v1/skills
Cookie: jarvis_registry_session=<token>
X-Jarvis-CSRF: <hmac>
Content-Type: application/json

{
  "name": "mongoose-to-beanie",
  "description": "Convert Mongoose schemas to Beanie models",
  "body": "# Mongoose to Beanie\n\nFollow these instructions...\n",
  "category": "development",
  "tags": ["python", "mongodb"],
  "files": [
    {
      "relativePath": "scripts/run_review.sh",
      "content": "#!/usr/bin/env bash\nset -euo pipefail\n",
      "mimeType": "text/x-shellscript",
      "isExecutable": true
    },
    {
      "relativePath": "assets/logo.png",
      "body": "<base64-encoded>",
      "mimeType": "image/png"
    }
  ]
}

Response¶

201 Created — returns SkillDetailResponse (same shape as GET detail). The response files[] reflects the files just created.

Errors¶

3. Get Skill Detail¶

GET /skills/{skill_id}

Returns full skill detail including file metadata (without file content) and the caller's permissions.

Path Parameters¶

Response¶

200 OK

{
  "id": "<skill-objectid>",
  "name": "mongoose-to-beanie",
  "displayTitle": "Mongoose to Beanie",
  "description": "Convert Mongoose schemas to Beanie models",
  "body": "# Mongoose to Beanie\n\nFollow these instructions...\n",
  "frontmatter": {
    "name": "mongoose-to-beanie",
    "description": "Convert Mongoose schemas to Beanie models",
    "alwaysApply": false
  },
  "category": "development",
  "tags": ["python", "mongodb"],
  "version": 3,
  "fileCount": 1,
  "enabled": true,
  "alwaysApply": false,
  "userInvocable": true,
  "disableModelInvocation": false,
  "allowedTools": null,
  "author": "<user-objectid>",
  "authorName": "Jane Doe",
  "source": "inline",
  "sourceMetadata": null,
  "createdByRegistry": true,
  "createdAt": "2026-08-01T12:00:00Z",
  "updatedAt": "2026-08-05T10:01:00Z",
  "files": [
    {
      "id": "<file-objectid>",
      "relativePath": "references/guide.md",
      "mimeType": "text/markdown",
      "bytes": 2048,
      "isBinary": false,
      "isExecutable": false,
      "source": "registry-inline"
    }
  ],
  "permissions": {
    "VIEW": true,
    "EDIT": true,
    "DELETE": true,
    "SHARE": true
  }
}

4. Get Skill Content (Sync-Down)¶

GET /skills/{skill_id}/content

Returns the data required to reconstruct the local skill directory. This is the primary endpoint for CLI sync. Accepts both session cookie and Bearer token authentication.

Response¶

200 OK

{
  "id": "<skill-objectid>",
  "name": "mongoose-to-beanie",
  "description": "Convert Mongoose schemas to Beanie models",
  "body": "# Mongoose to Beanie\n\nFollow these instructions...\n",
  "frontmatter": {
    "name": "mongoose-to-beanie",
    "description": "Convert Mongoose schemas to Beanie models"
  },
  "alwaysApply": false,
  "disableModelInvocation": false,
  "userInvocable": true,
  "allowedTools": null,
  "category": "development",
  "createdByRegistry": true,
  "files": [
    {
      "relativePath": "references/guide.md",
      "content": "# Guide\n\nReference content here.",
      "mimeType": "text/markdown",
      "bytes": 2048,
      "isBinary": false,
      "isExecutable": false,
      "source": "registry-inline"
    },
    {
      "relativePath": "assets/icon.png",
      "body": "<base64-encoded>",
      "mimeType": "image/png",
      "bytes": 4096,
      "isBinary": true,
      "isExecutable": false,
      "source": "registry-inline"
    }
  ]
}

Each entry in files[] is a SkillFileResponse: text registry-inline files carry content; binary registry-inline files carry body (base64) instead, with content omitted.

File Availability¶

Files with source: "registry-inline" include their content. Files created in Jarvis Chat (other source values) return available: false with a reason:

{
  "relativePath": "data/config.json",
  "mimeType": "application/json",
  "bytes": 512,
  "isBinary": false,
  "source": "github",
  "available": false,
  "unavailableReason": "File content is not available in Registry because it was created in Jarvis Chat."
}

5. Get File Content¶

GET /skills/{skill_id}/files/{file_path}

Returns content for a single file. Registry-inline files return text content or base64-encoded binary. Chat-created files return available: false.

Path Parameters¶

Response¶

200 OK — Registry-inline text file:

{
  "relativePath": "references/guide.md",
  "content": "# Guide\n\nReference content here.",
  "mimeType": "text/markdown",
  "isBinary": false,
  "available": true
}

200 OK — Registry-inline binary file:

{
  "relativePath": "assets/icon.png",
  "body": "<base64-encoded>",
  "mimeType": "image/png",
  "isBinary": true,
  "available": true
}

200 OK — Chat-created file:

{
  "relativePath": "data/config.json",
  "mimeType": "application/json",
  "isBinary": false,
  "available": false,
  "unavailableReason": "File content is not available in Registry because it was created in Jarvis Chat."
}

5b. Upsert File¶

PUT /skills/{skill_id}/files/{file_path}

Create or replace a single registry-inline supporting file. Supports incremental file management — the client sends only the file being changed, not the whole skill. Requires EDIT on the skill and createdByRegistry = true. Bumps the skill's version and refreshes updatedAt.

Request Body — SkillFileUpsertRequest¶

Same field set as SkillFileInput (see §2) without relativePath (comes from the URL): content or body (exactly one), optional mimeType, isExecutable, isBinary.

Response¶

• 201 Created — the file did not exist and was created.
• 200 OK — the file existed and was replaced.

Body: SkillFileMetadataResponse.

{
  "id": "<file-objectid>",
  "relativePath": "scripts/run_review.sh",
  "mimeType": "text/x-shellscript",
  "bytes": 42,
  "isBinary": false,
  "isExecutable": true,
  "source": "registry-inline"
}

Errors¶

5c. Delete File¶

DELETE /skills/{skill_id}/files/{file_path}

Remove a single registry-inline supporting file. Requires EDIT and createdByRegistry = true. Bumps the skill's version and refreshes updatedAt.

Response¶

204 No Content.

Errors¶

6. Update Skill¶

PATCH /skills/{skill_id}

Partial update of metadata only. Supporting files are managed via PUT/DELETE /skills/{skill_id}/files/{file_path} (§5b, §5c) so callers only re-send the file being changed. Increments version and updates updatedAt. Frontmatter fields (name, description, alwaysApply, userInvocable, disableModelInvocation, allowedTools) are automatically synced to the frontmatter object.

Request Body¶

All fields are optional. Only include fields to update.

Sending null for non-nullable fields returns 422 Unprocessable Entity. An empty body (no fields) returns the current state without incrementing version.

Request Example¶

PATCH /api/v1/skills/<skill-objectid>
Cookie: jarvis_registry_session=<token>
X-Jarvis-CSRF: <hmac>
Content-Type: application/json

{
  "description": "Updated description",
  "category": "migration"
}

Response¶

200 OK — returns SkillDetailResponse.

Errors¶

7. Delete Skill¶

DELETE /skills/{skill_id}

Permanently deletes a skill and all its files. Only skills created in Registry (createdByRegistry: true) can be deleted. Chat-created skills return 409 Conflict.

The operation is atomic (MongoDB transaction): deletes skill files, the skill document, and all ACL entries.

Response¶

204 No Content

Errors¶

8. Toggle Skill¶

POST /skills/{skill_id}/toggle

Enables or disables a skill. Requires EDIT permission.

Request Body¶

Request Example¶

POST /api/v1/skills/<skill-objectid>/toggle
Cookie: jarvis_registry_session=<token>
X-Jarvis-CSRF: <hmac>
Content-Type: application/json

{
  "enabled": false
}

Response¶

200 OK

{
  "id": "<skill-objectid>",
  "enabled": false
}

Error Responses¶

All errors use the standard FastAPI response shape:

{
  "detail": "Error message"
}

Local Directory Reconstruction¶

The CLI creates one directory per Skill:

<skills-root>/mongoose-to-beanie/
├── SKILL.md
└── references/
    └── guide.md

SKILL.md is reconstructed by combining promoted fields with frontmatter and body:

---
name: mongoose-to-beanie
description: Convert Mongoose schemas to Beanie models
always-apply: false
disable-model-invocation: false
user-invocable: true
category: development
---

# Mongoose to Beanie

Follow these instructions...

When allowedTools is non-null, it maps to allowed-tools in the frontmatter. When isExecutable is true on a supporting file, the CLI must set the file's execute permission (chmod +x) after writing.

Clients should still normalize relativePath values before writing to disk. On the write side, Registry already rejects absolute paths, parent traversal (..), duplicate paths, backslashes, non-normalized POSIX paths, and the reserved SKILL.md name with 422 Unprocessable Entity.

Scopes¶

Defined in registry-pkgs/src/registry_pkgs/scopes.yml: