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://next.clanker.engineer/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://next.clanker.engineer/api/v1/skills/readme-generator/upload \
  -H "X-Auth-Token: your-session-token" \
  -F "[email protected]" \
  -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.

A bundle is checked before anything is unpacked. An archive is refused with 413 PAYLOAD_TOO_LARGE if it holds more than 1,000 entries, any single file over 50 MB uncompressed, or more than 100 MB uncompressed in total. The limit is on the unpacked size, so a small .zip that expands past it is refused too.

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://next.clanker.engineer/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://next.clanker.engineer/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://next.clanker.engineer/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.engineer/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://next.clanker.engineer/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://next.clanker.engineer/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"
    }
  }'

For a repository run, the branch is mounted in the sandbox rather than cloned, so it is usable in seconds and file contents are fetched as they are read. The sandbox never holds your GitHub token: git traffic goes through the platform, which attaches the credential on its own side.

Skills are not executed over MCP. There is no execute-skill MCP tool — a tracked skill run is 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).

Asking an agent in chat to use your skill is the other path: it loads your SKILL.md and follows it in its own sandbox, where your scripts/ are staged at /home/user/skills/<slug>/. Write instructions that work when read and followed directly — that is what an agent does with them.

Re-run with New Input

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

curl -X POST https://next.clanker.engineer/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://next.clanker.engineer/api/v1/skills \
  -H "X-Auth-Token: your-session-token"

Paginated:

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

Get Skill Details

curl https://next.clanker.engineer/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://next.clanker.engineer/api/v1/skills/readme-generator/manifest \
  -H "X-Auth-Token: your-session-token"

Download Skill File

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

Uninstall Skill

curl -X POST https://next.clanker.engineer/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