Creating Skills

Create, test, and install custom AI skills using the Clanker API.

What is a Skill?

A skill is a reusable AI task defined by a SKILL.md file. When executed, the AI agent reads the instructions in SKILL.md and follows them to complete the task. Skills are identified by a slug (e.g., readme-generator) and invoked as slash commands (/readme-generator).

Creating a Skill via API

Method 1: Upload a Skill Bundle

Upload your own SKILL.md (plus any supporting files) as a new skill bundle. The bundle must contain a SKILL.md file. Send it either as a multipart .zip or as a JSON files map (the server builds the ZIP for you).

curl -X POST https://clanker.net/api/v1/skills/readme-generator/upload \
  -H "X-Auth-Token: your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "README Generator",
    "description": "Generate comprehensive README files for any project",
    "category": "development",
    "files": {
      "SKILL.md": "---\nname: README Generator\nslug: readme-generator\ndescription: Generate comprehensive README files for any project\ncategory: development\n---\n\n# README Generator\n\nGenerate comprehensive README files for any project.\n\n## Instructions\n\n1. Parse the project description to identify name, language, and type\n2. Generate Installation, Usage, API Reference, and Contributing sections\n3. Use code blocks with language hints and tables for parameters\n\n## Output\n\nA single markdown file ready to use as README.md."
    }
  }'

To upload a .zip directly, send a multipart request with a file part instead of the JSON files map:

curl -X POST https://clanker.net/api/v1/skills/readme-generator/upload \
  -H "X-Auth-Token: your-session-token" \
  -F "file=@readme-generator.zip" \
  -F "name=README Generator" \
  -F "category=development"

When name, description, or category are omitted, they are parsed from the SKILL.md frontmatter in the bundle.

Response:

{
  "name": "README Generator",
  "slug": "readme-generator",
  "description": "Generate comprehensive README files for any project",
  "category": "development",
  "bundleType": "single",
  "storagePath": "skills/user123/readme-generator",
  "filesCount": 1
}

Once uploaded, run the skill via POST /api/v1/executions (see Executing Skills).

Method 2: Install from Artifact

When a skill execution produces an artifact, you can install that artifact as a new skill:

curl -X POST https://clanker.net/api/v1/skills/my-custom-skill/install \
  -H "X-Auth-Token: your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "My Custom Skill",
    "description": "A skill generated from a previous execution",
    "category": "productivity"
  }'

Response:

{
  "name": "My Custom Skill",
  "slug": "my-custom-skill",
  "description": "A skill generated from a previous execution",
  "category": "productivity",
  "bundleType": "single",
  "storagePath": "skills/user123/my-custom-skill"
}

Method 3: Install from Marketplace

Install an existing skill by slug:

curl -X POST https://clanker.net/api/v1/skills/readme-generator/install \
  -H "X-Auth-Token: your-session-token"

No request body needed — the skill metadata is fetched from the marketplace catalog.

SKILL.md Structure

Every skill is defined by a SKILL.md file. Metadata is provided via YAML frontmatter:

---
name: README Generator
slug: readme-generator
description: Generate comprehensive README files for any project
category: development
---

# README Generator

Generate comprehensive README files for any project.

## Instructions

Detailed instructions for the AI agent:

1. How to interpret user input
2. What actions to take
3. How to format output

## Examples

### Input
"CLI tool for converting CSV to JSON, written in Go"

### Output
A README with Installation, Usage, and API Reference sections.

## Output Format

Describe the expected output format:
- File type (markdown, JSON, code, etc.)
- Structure and sections

Skill Categories

Category	Use For
`productivity`	Document generation, task helpers
`development`	Code-related tasks, reviews, testing
`creative`	Content creation, writing, design
`data`	Data processing, analysis, transformation
`mcp`	MCP servers, tool development

Executing Skills

REST API

curl -X POST https://clanker.net/api/v1/skills/readme-generator/run \
  -H "x-api-key: ck_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Create a README for my TypeScript CLI that converts YAML to JSON"
  }'

Response:

{
  "executionId": "exec_abc123",
  "skillName": "README Generator",
  "status": "started",
  "message": "Execution started. Mint a signed stream URL to connect live."
}

To stream live output, call GET /api/v1/executions/exec_abc123/stream-token (authenticated, ownership-checked) → { "sseUrl": "https://sandbox.clanker.net/executions/exec_abc123/events?ts=…&sig=…" }, then open that signed URL (see Real-time streaming). The create response does NOT return an SSE URL, and there is no same-origin /api/v1/executions/:id/events GET — the live stream is a short-lived signed capability minted separately.

{
  "note": "stream-token, not the create response, yields the SSE URL"
}

Connect to the SSE stream for real-time output, or poll GET /api/v1/executions/:id/status until the execution completes.

With File Attachments

curl -X POST https://clanker.net/api/v1/skills/code-reviewer/run \
  -H "x-api-key: ck_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Review this code for security issues",
    "attachments": [
      {
        "name": "app.ts",
        "content": "aW1wb3J0IGV4cHJlc3MgZnJvbSAnZXhwcmVzcyc7...",
        "encoding": "base64",
        "mimeType": "application/typescript"
      }
    ]
  }'

Supported attachment types: text files, images (PNG, JPEG, GIF, WebP), PDFs, and ZIP archives.

With GitHub Connector

curl -X POST https://clanker.net/api/v1/skills/code-reviewer/run \
  -H "x-api-key: ck_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Review the latest changes for security issues",
    "connector": {
      "type": "github",
      "repo": "owner/repo",
      "branch": "main"
    }
  }'

Skills are not executed over MCP. There is no execute-skill MCP tool — skill runs are started through the REST API (POST /api/v1/skills/:slug/run or POST /api/v1/executions). Over MCP you can discover and install skills and monitor runs (get-execution-status, list-executions, cancel-execution), but the run itself is kicked off via REST or a slash command in chat.

Re-run with New Input

Re-execute using the same skill and settings from a previous execution:

curl -X POST https://clanker.net/api/v1/executions/exec_abc123/rerun \
  -H "x-api-key: ck_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Same project but add a Contributing section and badges"
  }'

Managing Skills

List Installed Skills

curl https://clanker.net/api/v1/skills \
  -H "X-Auth-Token: your-session-token"

Paginated:

curl "https://clanker.net/api/v1/skills?limit=20&offset=0" \
  -H "X-Auth-Token: your-session-token"

Get Skill Details

curl https://clanker.net/api/v1/skills/readme-generator \
  -H "X-Auth-Token: your-session-token"

Response:

{
  "id": 42,
  "name": "README Generator",
  "slug": "readme-generator",
  "description": "Generate comprehensive README files",
  "category": "development",
  "prompt": "# README Generator\n\nGenerate comprehensive README files...",
  "bundleType": "single",
  "storagePath": "skills/user123/readme-generator",
  "repository": "https://github.com/user/readme-generator",
  "commitHash": "abc123"
}

Get Skill Manifest (Multi-File Skills)

curl https://clanker.net/api/v1/skills/readme-generator/manifest \
  -H "X-Auth-Token: your-session-token"

Download Skill File

curl https://clanker.net/api/v1/skills/readme-generator/file/templates/readme.md \
  -H "X-Auth-Token: your-session-token"

Uninstall Skill

curl -X POST https://clanker.net/api/v1/skills/readme-generator/uninstall \
  -H "X-Auth-Token: your-session-token"

Writing Good SKILL.md

Be Specific About Intent

## Instructions

You are a README generator. Your job is to:
1. Analyze the user's project description
2. Create a comprehensive README.md file
3. Include all standard sections (Installation, Usage, API, etc.)
4. Add relevant badges if the project type is identifiable

Do NOT:
- Make assumptions about implementation details
- Include placeholder text like "TODO"
- Add sections that don't apply to the project

Handle Edge Cases

## Edge Cases

- If user doesn't specify a language, infer from context
- If project type is unclear, create a generic template
- If user requests features not supported, explain limitations

Define Output Format

## Output Format

Generate a single markdown file with:
- H1 title matching the project name
- Badges section (if applicable)
- Description paragraph
- Installation section with code blocks
- Usage section with examples
- API Reference (if applicable)
- License section

Next Steps

Skills Concepts - Skill architecture and lifecycle
MCP Client Setup - Test skills via MCP
Workflows - Chain skills into multi-step workflows