Skills

Skills are the core building blocks of clanker.engineer. Each skill is a specialized AI agent designed to perform a specific task.

What is a Skill?

A skill consists of:

• Name - Human-readable identifier (e.g., “README Generator”)
• Slug - URL-safe identifier (e.g., readme-generator)
• Description - Brief explanation of what the skill does
• Category - Classification (productivity, development, creative, etc.)
• SKILL.md - The prompt/instructions that define the skill’s behavior

Skill Categories

Marketplace vs Installed Skills

Marketplace Skills

The marketplace contains 370+ community-contributed skills that you can browse and install.

# List marketplace skills via API
GET /api/v1/marketplace/skills

# Browse marketplace via REST API
GET /api/v1/marketplace/skills

# Get skill details via MCP
{
  "tool": "get-skill-details",
  "arguments": {
    "slug": "code-reviewer"
  }
}

Installed Skills

Once you install a skill, it’s added to your personal library and can be executed.

# List your installed skills via MCP
{
  "tool": "list-installed-skills",
  "arguments": {
    "limit": 20
  }
}

Installing Skills

Via Mobile App

1. Browse the Marketplace tab
2. Tap a skill to view details
3. Tap Install

Via MCP

{
  "tool": "install-skill",
  "arguments": {
    "slug": "readme-generator"
  }
}

Via REST API

POST /api/v1/skills/:slug/install

Executing Skills

Skills are executed with natural language input. The skill’s SKILL.md provides context and instructions to the AI.

A skill runs one of two ways, and they are not the same thing.

In chat, the agent loads the skill and carries it out in its own sandbox, inside the conversation. Nothing is queued and no execution record appears.

Through the REST API (below), the skill runs as a tracked execution you can poll, stream and cancel. This is the path for anything unattended.

There is no execute-skill tool in either case — over MCP you discover, install and monitor skill runs.

Via REST API

For programmatic use (bots, CI/CD, external integrations), use the Sessions API — it’s the preferred path and compatible with managed-agent providers:

# Step 1: create the execution (skill_slug and a non-empty input are both required)
POST /api/v1/executions
{ "skill_slug": "readme-generator", "input": "Create a README for my TypeScript CLI tool" }

# Step 2: mint the signed stream URL, then connect an EventSource to it
GET /api/v1/executions/:id/stream-token   → { "sseUrl": "…?ts=…&sig=…" }

# Step 3: send the user.message that starts the run
POST /api/v1/executions/:id/events
{ "events": [{ "type": "user.message", "content": [{ "type": "text", "text": "..." }] }] }

For interactive/dashboard use only, a single-call shortcut is also available:

POST /api/v1/skills/:slug/run
Content-Type: application/json

{
  "input": "Create a README for my TypeScript CLI tool"
}

Execution Response

Both paths return an executionId. To receive real-time output, mint a signed stream URL and connect an EventSource to it — this API exposes no GET stream of its own, and POST …/events is the INPUT channel, not the output one:

GET /api/v1/executions/:executionId/stream-token
→ { "sseUrl": "…/executions/:executionId/events?ts=…&sig=…" }

See Executions API for the full Sessions API reference.

Skill Structure

A skill is defined by a SKILL.md file that contains:

# Skill Name

## Description
Brief description of what this skill does.

## Instructions
Detailed instructions for the AI agent:
- What to do with user input
- How to format output
- Any constraints or requirements

## Examples
Example inputs and expected outputs.

See Creating Skills for a complete guide.

Skill Metadata

Best Practices

1. Be specific - Skills that do one thing well are more useful than generic skills
2. Provide examples - Include example inputs and outputs in SKILL.md
3. Handle edge cases - Describe how to handle unexpected input
4. Test thoroughly - Execute your skill with various inputs before publishing