Skills API

Manage skills in the Skill Library. Skills are reusable knowledge packages (markdown instructions) that teach agents how to handle specific tasks.

Skills are separate from Prompts — prompts are templates for LLM messages, while skills are behavioral instructions for agents.

Authentication

All endpoints require a valid API key via the Authorization header:

Authorization: Bearer sk-prod-...

Skill Object

Field	Type	Description
`id`	string	Unique skill ID
`name`	string	Skill name
`description`	string	What the skill does and when to use it
`content`	string	Full skill content (markdown with optional YAML frontmatter)
`variables`	array	Template variables extracted from `{{name}}` syntax
`tags`	array	Tags for categorization and discovery
`category`	string	Skill category (e.g., "tools", "agent", "support")
`currentVersion`	number	Current version number
`ownerId`	string	Owner user ID
`ownerName`	string	Owner display name
`sharedWith`	array	User IDs with read access
`isPublic`	boolean	Whether the skill is publicly visible
`source`	string	Origin: `user`, `marketplace`, `github:owner/repo`
`mcpTools`	array	MCP tool names this skill references
`githubUrl`	string	GitHub source URL (if imported)
`usageCount`	number	How many times the skill has been used
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Version Object

Field	Type	Description
`id`	string	Version ID
`skillId`	string	Parent skill ID
`versionNumber`	number	Sequential version number
`content`	string	Full content snapshot at this version
`variables`	array	Variables at this version
`changeNote`	string	Description of what changed
`createdAt`	string	ISO 8601 timestamp
`createdBy`	string	User ID who created this version
`createdByName`	string	Display name

Endpoints

List Skills

GET /api/v1/skills

Query Parameters:

Parameter	Type	Description
`search`	string	Search by name or description
`tags`	string	Comma-separated tags to filter by
`category`	string	Filter by category
`limit`	number	Max results per page (default: 20, max: 100)
`offset`	number	Pagination offset

Response:

{
  "data": [
    {
      "id": "abc123",
      "name": "Product Search",
      "description": "Semantic search across product catalog",
      "tags": ["search", "milvus"],
      "category": "tools",
      "currentVersion": 3,
      "ownerName": "Admin",
      "isPublic": false,
      "source": "marketplace",
      "usageCount": 42,
      "updatedAt": "2026-03-27T00:00:00.000Z"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}

Create Skill

POST /api/v1/skills

Request Body:

{
  "name": "Product Search",
  "description": "Semantic search across the product catalog",
  "content": "# Product Search\n\n## When to Use\nUser asks to find products...\n\n## Instructions\n...",
  "tags": ["search", "milvus"],
  "category": "tools",
  "mcpTools": ["product_search"]
}

Field	Type	Required	Description
`name`	string	Yes	Skill name
`content`	string	Yes	Markdown content (supports `{{variables}}`)
`description`	string	No	Description
`tags`	array	No	Tags for discovery
`category`	string	No	Category
`mcpTools`	array	No	MCP tool names this skill uses
`source`	string	No	Source identifier (default: "user")

Response: 201 Created

{
  "data": { "skillId": "abc123" }
}

Get Skill

GET /api/v1/skills/:id

Returns the full skill with content (excluding embedding vector).

Response:

{
  "data": {
    "id": "abc123",
    "name": "Product Search",
    "content": "# Product Search\n\n## When to Use\n...",
    "variables": [
      { "name": "limit", "required": true }
    ],
    "tags": ["search"],
    "category": "tools",
    "currentVersion": 3,
    "mcpTools": ["product_search"]
  }
}

Update Skill

PUT /api/v1/skills/:id

Content changes automatically create a new version.

Request Body:

{
  "content": "# Updated Product Search\n\n...",
  "changeNote": "Added error handling instructions"
}

Delete Skill

DELETE /api/v1/skills/:id

Deletes the skill and all its versions. Cannot be undone.

List Versions

GET /api/v1/skills/:id/versions

Returns all versions, newest first.

Restore Version

POST /api/v1/skills/:id/restore

Creates a new version with the restored content.

Request Body:

{
  "versionNumber": 2
}

Update Scope

PATCH /api/v1/skills/:id/scope

Re-scope an existing skill (per-agent isolation Phase 4). Owner-only. The owner can move a skill between user-global / agent-scoped / app-scoped / workflow-scoped without rewriting any content.

Request Body (either nested or flat top-level)

{
  "scope": { "agentId": "agent-123" }
}

Empty / whitespace values collapse to null. Sending {"scope": {}} is the explicit opt-out to user-global. Cross-app rows return 404 (existence- leak prevention).

Response 200 OK

{
  "success": true,
  "scope": { "agentId": "agent-123", "appId": null, "workflowId": null }
}

Duplicate Skill

POST /api/v1/skills/:id/duplicate

Creates a copy owned by the current user with " (Copy)" suffix.

Render Skill

POST /api/v1/skills/:id/render

Renders the skill content with variable substitution.

Request Body:

{
  "variables": {
    "limit": "10",
    "category": "Handguns"
  }
}

Response:

{
  "data": {
    "content": "Rendered content with variables replaced...",
    "skillId": "abc123",
    "name": "Product Search"
  }
}

Record Usage

POST /api/v1/skills/:id/usage

Increment the usage counter for analytics.

Assess Skill

POST /api/v1/skills/:id/assess

Runs the quality ruleset over the skill's current content and returns a score plus recommendations. Modeled after Anthropic's skill-building guide — checks structure, presence of "When to Use", instruction clarity, variable usage, etc.

Path Parameters:

Name	Type	Required	Description
`id`	string	Yes	Skill ID

Request Body: None.

Response:

{
  "data": {
    "score": 82,
    "maxScore": 100,
    "grade": "B",
    "checks": [
      {
        "id": "has-when-to-use",
        "label": "Includes a 'When to Use' section",
        "passed": true,
        "weight": 10
      },
      {
        "id": "instructions-actionable",
        "label": "Instructions are concrete and actionable",
        "passed": false,
        "weight": 15,
        "recommendation": "Replace abstract guidance with step-by-step actions."
      }
    ],
    "recommendations": [
      "Add a 'When to Use' section so agents know when to invoke this skill.",
      "Document each variable's expected type and example value."
    ]
  }
}

Required Scope: skills:read

Import from GitHub

POST /api/v1/skills/import-github

Imports a skill from a GitHub repository containing a SKILL.md file with YAML frontmatter.

Request Body:

{
  "githubUrl": "https://github.com/owner/repo-name"
}

Python SDK

from strongly import Strongly

client = Strongly(api_key="sk-prod-...")

# List skills
for skill in client.skills.list(category="tools"):
    print(f"{skill.name} (v{skill.current_version})")

# Create a skill
result = client.skills.create({
    "name": "My Skill",
    "content": "# My Skill\n\nInstructions...",
    "tags": ["custom"],
})
skill_id = result["data"]["skillId"]

# Get skill content
skill = client.skills.retrieve(skill_id)
print(skill.content)

# Update with versioning
client.skills.update(skill_id, {
    "content": "# Updated content",
    "changeNote": "Improved instructions",
})

# Render with variables
rendered = client.skills.render(skill_id, {"limit": "10"})
print(rendered.content)

# Import from GitHub
client.skills.import_from_github("https://github.com/owner/my-skill")

# List versions
versions = client.skills.list_versions(skill_id)
for v in versions:
    print(f"v{v.version_number}: {v.change_note}")

Scopes

Scope	Endpoints
`skills:read`	GET /skills, GET /skills/:id, GET /skills/:id/versions, POST /skills/:id/render, POST /skills/:id/usage, POST /skills/:id/assess
`skills:write`	POST /skills, PUT /skills/:id, DELETE /skills/:id, POST /skills/:id/restore, POST /skills/:id/duplicate, POST /skills/import-github

Authentication​

Skill Object​

Version Object​

Endpoints​

List Skills​

Create Skill​

Get Skill​

Update Skill​

Delete Skill​

List Versions​

Restore Version​

Update Scope​

Duplicate Skill​

Render Skill​

Record Usage​

Assess Skill​

Import from GitHub​

Python SDK​

Scopes​

Authentication

Skill Object

Version Object

Endpoints

List Skills

Create Skill

Get Skill

Update Skill

Delete Skill

List Versions

Restore Version

Update Scope

Duplicate Skill

Render Skill

Record Usage

Assess Skill

Import from GitHub

Python SDK

Scopes