Agent Skills API Reference

Overview

The Agent Skills API provides endpoints for browsing the skills marketplace, installing skills, and managing skill enablement. Skills are specialized AI capabilities that enhance content generation and analysis.

Base URL: http://localhost:8201 Authentication: Bearer token required for most endpoints Tag: Agent Skills

API Endpoints

Browse Skills Marketplace

List All Skills

GET /api/agent-skills

Browse available skills in the marketplace with filtering and pagination.

Query Parameters:

Parameter	Type	Default	Description
`category`	string	`null`	Filter by skill category (e.g., `entity`, `document`)
`search`	string	`null`	Full-text search across skill names and descriptions
`featured`	boolean	`false`	Only return featured skills
`limit`	integer	`50`	Max results (1-200)
`offset`	integer	`0`	Pagination offset

Response:

{
  "skills": [
    {
      "skill_id": "character_writer",
      "name": "Character Writer",
      "description": "Specialized in creating deep, consistent character profiles with rich backstories and authentic voice.",
      "category": "entity",
      "tags": ["character", "storytelling", "persona"],
      "definition": {
        "capabilities": [
          "backstory_generation",
          "personality_modeling",
          "relationship_mapping",
          "voice_definition",
          "motivation_analysis"
        ],
        "applies_to": ["Character"]
      },
      "prompt_template": "You are a Character Writer skill. Your task is to create deep, consistent character profiles...",
      "parameters": {
        "max_tokens": 500,
        "temperature": 0.7,
        "context_window": 2000
      },
      "min_tier": "free",
      "is_featured": false,
      "is_builtin": true,
      "usage_count": 42,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2026-02-20T14:22:00Z"
    }
  ],
  "total": 50,
  "limit": 50,
  "offset": 0
}

Example:

curl -X GET "http://localhost:8201/api/agent-skills?category=entity&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Skill Details

GET /api/agent-skills/{skill_id}

Retrieve complete details for a specific skill.

Path Parameters:

Parameter	Type	Description
`skill_id`	string	Unique skill identifier (e.g., `character_writer`)

Response:

{
  "skill_id": "character_writer",
  "name": "Character Writer",
  "description": "Specialized in creating deep, consistent character profiles with rich backstories and authentic voice.",
  "category": "entity",
  "tags": ["character", "storytelling", "persona"],
  "definition": {
    "capabilities": [
      "backstory_generation",
      "personality_modeling",
      "relationship_mapping",
      "voice_definition",
      "motivation_analysis"
    ],
    "applies_to": ["Character"]
  },
  "prompt_template": "You are a Character Writer skill. Your task is to create deep, consistent character profiles...",
  "parameters": {
    "max_tokens": 500,
    "temperature": 0.7,
    "context_window": 2000
  },
  "min_tier": "free",
  "is_featured": false,
  "is_builtin": true,
  "usage_count": 42,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2026-02-20T14:22:00Z"
}

Example:

curl -X GET "http://localhost:8201/api/agent-skills/character_writer" \
  -H "Authorization: Bearer YOUR_TOKEN"

Tenant Installations

List Installed Skills

GET /api/agent-skills/tenant/installed

List skills installed for the current user.

Query Parameters:

Parameter	Type	Default	Description
`enabled_only`	boolean	`false`	Only return enabled skills

Response:

{
  "skills": [
    {
      "installation_id": "inst-xyz789",
      "skill_id": "character_writer",
      "enabled": true,
      "source": "marketplace",
      "source_url": null,
      "installed_by": "user-456",
      "installed_at": "2026-02-28T09:15:00Z",
      "updated_at": "2026-03-01T11:30:00Z"
    },
    {
      "installation_id": "inst-uvw456",
      "skill_id": "location_writer",
      "enabled": false,
      "source": "template_pack",
      "source_url": null,
      "installed_by": "user-456",
      "installed_at": "2026-02-20T14:00:00Z",
      "updated_at": "2026-02-20T14:00:00Z"
    }
  ]
}

Example:

# List all installed skills
curl -X GET "http://localhost:8201/api/agent-skills/tenant/installed" \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# List only enabled skills
curl -X GET "http://localhost:8201/api/agent-skills/tenant/installed?enabled_only=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Enabled Skills with Definitions

GET /api/agent-skills/tenant/enabled

Get all enabled skills with full definitions merged.

Response:

{
  "skills": [
    {
      "installation_id": "inst-xyz789",
      "skill_id": "character_writer",
      "enabled": true,
      "source": "marketplace",
      "installed_at": "2026-02-28T09:15:00Z",
      "definition": {
        "capabilities": ["backstory_generation", "personality_modeling", ...],
        "applies_to": ["Character"]
      },
      "prompt_template": "You are a Character Writer skill...",
      "parameters": {
        "max_tokens": 500,
        "temperature": 0.7
      }
    }
  ]
}

Example:

curl -X GET "http://localhost:8201/api/agent-skills/tenant/enabled" \
  -H "Authorization: Bearer YOUR_TOKEN"

Install a Skill

POST /api/agent-skills/tenant/install

Install a skill.

Request Body:

{
  "skill_id": "character_writer",
  "source": "marketplace",  // "marketplace", "template_pack", or "local"
  "source_url": "https://github.com/example/skills-repo"  // optional
}

Request Body Fields:

Field	Type	Required	Description
`skill_id`	string	Yes	Unique skill identifier
`source`	string	No	Default: `marketplace`
`source_url`	string	No	URL to skill source (e.g., GitHub repo)

Response:

{
  "message": "Skill 'character_writer' installed",
  "installation": {
    "installation_id": "inst-new123",
    "skill_id": "character_writer",
    "enabled": true,
    "source": "marketplace",
    "source_url": null,
    "installed_by": "user-456",
    "installed_at": "2026-03-10T08:45:00Z",
    "updated_at": "2026-03-10T08:45:00Z"
  }
}

Example:

curl -X POST "http://localhost:8201/api/agent-skills/tenant/install" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": "character_writer",
    "source": "marketplace"
  }'

Enable a Skill

POST /api/agent-skills/tenant/{skill_id}/enable

Enable an installed skill.

Path Parameters:

Parameter	Type	Description
`skill_id`	string	Unique skill identifier

Response:

{
  "message": "Skill 'character_writer' enabled",
  "installation": {
    "installation_id": "inst-xyz789",
    "skill_id": "character_writer",
    "enabled": true,
    "source": "marketplace",
    "installed_at": "2026-02-28T09:15:00Z",
    "updated_at": "2026-03-10T08:50:00Z"
  }
}

Example:

curl -X POST "http://localhost:8201/api/agent-skills/tenant/character_writer/enable" \
  -H "Authorization: Bearer YOUR_TOKEN"

Disable a Skill

POST /api/agent-skills/tenant/{skill_id}/disable

Disable an installed skill.

Path Parameters:

Parameter	Type	Description
`skill_id`	string	Unique skill identifier

Response:

{
  "message": "Skill 'character_writer' disabled",
  "installation": {
    "installation_id": "inst-xyz789",
    "skill_id": "character_writer",
    "enabled": false,
    "source": "marketplace",
    "installed_at": "2026-02-28T09:15:00Z",
    "updated_at": "2026-03-10T08:55:00Z"
  }
}

Example:

curl -X POST "http://localhost:8201/api/agent-skills/tenant/character_writer/disable" \
  -H "Authorization: Bearer YOUR_TOKEN"

Uninstall a Skill

DELETE /api/agent-skills/tenant/{skill_id}

Uninstall a skill.

Warning: This removes all installation metadata. The skill will need to be reinstalled to be used again.

Path Parameters:

Parameter	Type	Description
`skill_id`	string	Unique skill identifier

Response:

{
  "message": "Skill 'character_writer' uninstalled"
}

Example:

curl -X DELETE "http://localhost:8201/api/agent-skills/tenant/character_writer" \
  -H "Authorization: Bearer YOUR_TOKEN"

Registry Management (Admin Only)

Add/Update Skill in Registry

POST /api/agent-skills/registry

Add or update a skill in the marketplace registry. Requires admin or owner role.

Request Body:

{
  "skill_id": "custom_analyzer",
  "name": "Custom Analyzer",
  "description": "Specialized in analyzing narrative structures",
  "category": "document",
  "tags": ["analysis", "narrative", "structure"],
  "definition": {
    "capabilities": ["pattern_recognition", "structure_analysis"],
    "applies_to": ["DOC_SCRIPT", "DOC_GDD"]
  },
  "prompt_template": "You are a Custom Analyzer skill...",
  "parameters": {
    "max_tokens": 1000,
    "temperature": 0.5
  },
  "min_tier": "team",
  "is_featured": true,
  "is_builtin": false
}

Request Body Fields:

Field	Type	Required	Description
`skill_id`	string	Yes	Unique skill identifier
`name`	string	Yes	Human-readable name
`description`	string	No	Default: `""`
`category`	string	No	Skill category
`tags`	string[]	No	Default: `[]`
`definition`	object	No	Default: `{}`
`prompt_template`	string	No	Default: `""`
`parameters`	object	No	Default: `{}`
`min_tier`	string	No	Default: `"free"`
`is_featured`	boolean	No	Default: `false`
`is_builtin`	boolean	No	Default: `false`

Response:

{
  "skill_id": "custom_analyzer",
  "name": "Custom Analyzer",
  "description": "Specialized in analyzing narrative structures",
  "category": "document",
  "tags": ["analysis", "narrative", "structure"],
  "definition": { /* ... */ },
  "prompt_template": "You are a Custom Analyzer skill...",
  "parameters": { /* ... */ },
  "min_tier": "team",
  "is_featured": true,
  "is_builtin": false,
  "created_at": "2026-03-10T09:00:00Z",
  "updated_at": "2026-03-10T09:00:00Z"
}

Example:

curl -X POST "http://localhost:8201/api/agent-skills/registry" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_id": "custom_analyzer",
    "name": "Custom Analyzer",
    "description": "Specialized in analyzing narrative structures",
    "category": "document",
    "min_tier": "team"
  }'

Remove Skill from Registry

DELETE /api/agent-skills/registry/{skill_id}

Remove a skill from the registry. Requires admin or owner role.

Path Parameters:

Parameter	Type	Description
`skill_id`	string	Unique skill identifier

Response:

{
  "message": "Skill 'custom_analyzer' removed from registry"
}

Example:

curl -X DELETE "http://localhost:8201/api/agent-skills/registry/custom_analyzer" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Error Responses

404 Not Found

{
  "detail": "Skill 'nonexistent' not found"
}

403 Forbidden

{
  "detail": "Admin access required"
}

400 Bad Request

{
  "detail": "Invalid skill_id format"
}

Tier Requirements

Skills have min_tier values that determine which subscription tiers can install/use them:

Tier Value	Description
`free`	Available to all users
`indie`	Requires Indie tier subscription
`team`	Requires Team tier subscription
`enterprise`	Requires Enterprise tier subscription

Best Practices

Check before installing: Always call GET /api/agent-skills/{skill_id} to understand what a skill does before installing.
Use enabled_only filter: When listing skills for display in UI, use enabled_only=true to show active capabilities.
Track installation source: The source field helps audit where skills came from (marketplace, template pack, or custom).
Disable instead of uninstall: If you might need a skill again later, disable it instead of uninstalling to preserve configuration.
Admin operations: Registry management should only be done by admin/owner accounts. User-facing applications should only use installation operations (/tenant/* endpoints).

Agent Skills User Guide - How to use skills as a user
Plugin Marketplace API Reference - Similar API for plugins
AI Workshop - Using AI features in StudioBrain

REST API Reference Creating Agent Skills

Agent Skills API Reference

Overview

API Endpoints

Browse Skills Marketplace

List All Skills

Get Skill Details

Tenant Installations

List Installed Skills

Get Enabled Skills with Definitions

Install a Skill

Enable a Skill

Disable a Skill

Uninstall a Skill

Registry Management (Admin Only)

Add/Update Skill in Registry

Remove Skill from Registry

Error Responses

404 Not Found

403 Forbidden

400 Bad Request

Tier Requirements

Best Practices

Related Documentation