Skills API

Import and compile Claude Code skills into workflow.v1 specifications that can be executed via the Runs API.

Quick Reference

POST   /api/v1/skills/compile    Compile a skill from GitHub

Authentication

Skill endpoints require:

  • Secret key (mr_sk_*): Backend use with full project access

Runtime Requirements

/api/v1/skills/compile calls the ModelRelay Responses API under the hood to generate workflows. In practice you need:

  • A configured LLM provider key for the model you pass (or a default provider) so compilation can call /responses.
  • MODELRELAY_GITHUB_TOKEN (recommended) to avoid GitHub rate limits when fetching skill files.

Compile Skill

POST /api/v1/skills/compile

Fetches a Claude Code skill from a GitHub repository and compiles it into a workflow.v1 specification. The compiled workflow can then be executed using the Runs API.

Request Body

Field Type Required Description
source string Yes GitHub source reference (see Source Format)
model string No LLM model to use for workflow generation
max_attempts integer No Maximum attempts to regenerate on validation errors (default: 3, max: 5)

Response

Field Type Description
workflow object Compiled workflow.v1 specification
skill object Skill metadata
compiled_at datetime Timestamp of compilation
source_ref string Canonical source reference with resolved commit SHA

Skill Object

Field Type Description
name string Skill name from SKILL.md
description string Skill description
agents array List of agent names in the skill

Example

curl -X POST https://api.modelrelay.ai/api/v1/skills/compile \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "github:shanev/skills/unslopify@main"
  }'

Response

{
  "workflow": {
    "kind": "workflow.v1",
    "name": "unslopify",
    "nodes": [
      {
        "id": "type-strictness",
        "type": "llm.responses",
        "input": {...}
      },
      {
        "id": "srp",
        "type": "llm.responses",
        "input": {...}
      },
      {
        "id": "fail-fast",
        "type": "llm.responses",
        "input": {...}
      },
      {
        "id": "dry",
        "type": "llm.responses",
        "input": {...}
      },
      {
        "id": "aggregate",
        "type": "llm.responses",
        "deps": ["type-strictness", "srp", "fail-fast", "dry"],
        "input": {...}
      }
    ],
    "outputs": [
      {"name": "report", "from": "aggregate"}
    ]
  },
  "skill": {
    "name": "unslopify",
    "description": "Tactical code cleanup focusing on type strictness, SRP, fail-fast, and DRY",
    "agents": ["dry-analyzer", "fail-fast-analyzer", "srp-analyzer", "type-strictness-analyzer"]
  },
  "compiled_at": "2026-01-06T12:34:56Z",
  "source_ref": "github:shanev/skills/unslopify@abc123def456"
}

Source Format

The source field specifies where to fetch the skill from. Currently, GitHub repositories are supported.

GitHub Source

github:owner/repo/path@ref
Component Required Description
owner Yes GitHub repository owner
repo Yes Repository name
path No Path to skill directory within repo (defaults to root)
ref No Git ref (branch, tag, or commit SHA; defaults to main)

Examples

Source Description
github:shanev/skills/unslopify Skill at /unslopify in repo, main branch
github:shanev/skills/unslopify@v1.0.0 Specific tag
github:shanev/skills/unslopify@abc123 Specific commit
github:acme/internal-skills Skill at repo root

Skill Structure

A Claude Code skill must contain:

skill-name/
  SKILL.md           # Skill manifest (required)
  agents/            # Agent definitions (required, at least one)
    analyzer.md
    reviewer.md
  commands/          # Command definitions (required, at least one)
    default.md
  reference/         # Reference documentation (optional)
    guidelines.md

SKILL.md

The skill manifest with YAML frontmatter:

---
name: my-skill
description: What this skill does
version: 1.0.0
---

# My Skill

Additional documentation about the skill.

Agent Files

Each agent is a markdown file with frontmatter:

---
name: analyzer
description: Analyzes code for issues
tools:
  - Read
  - Grep
  - Glob
---

You are a code analyzer. Your job is to...

Command Files

Commands orchestrate agents:

---
name: default
description: Run the analysis
---

Run the following agents in parallel:
- agents/analyzer.md
- agents/reviewer.md

Then aggregate their results.

Error Responses

Status Code Description
400 invalid_source Source format is invalid
404 skill_not_found Skill repository or path not found
422 parse_failed Skill files could not be parsed
422 generation_failed Workflow generation failed
429 rate_limited GitHub API rate limit exceeded

Error Response Format

{
  "error": "api_error",
  "code": "skill_not_found",
  "message": "Skill not found at github:owner/repo/path"
}

Caching

Compiled workflows are deterministic for a given commit SHA. When you specify a branch or tag, the API resolves it to a commit SHA and includes it in source_ref. You can cache compiled workflows keyed by source_ref to avoid recompilation.

Next Steps