API and execution reference

This page covers how applications and agents call SkillGild: base URLs, authentication, every public and account endpoint, the run pipeline, idempotency, webhooks and error codes.

#Conventions

curl https://api.skillgild.com/v1
# {"name":"SkillGild API","version":"v1"}

#Authentication

Send every credential as a bearer token:

Authorization: Bearer <token>

A token that starts with sg_live_ is treated as an API key. Anything else is treated as a session token (JWT).

#How an API key is validated

SkillGild accepts an API key only if all of these hold:

• the key exists and has not been revoked;
• it has not expired;
• if it belongs to a connected device, that device has not been revoked;
• the owning user is active and not banned;
• the key has the runtime:execute scope.

#Authentication errors

#Catalog (public, no auth)

#GET /v1/skills

Lists published, public, hosted skills, ordered by name.

curl "https://api.skillgild.com/v1/skills?q=accessibility&limit=20"

{
  "data": {
    "items": [
      {
        "id": "0b6f8f9e-4c4d-4d0a-9d3e-2f1c8a7b6e5d",
        "slug": "accessibility-audit",
        "name": "Accessibility audit",
        "description": "Reviews a UI description or component code and returns prioritized WCAG 2.2 issues with fixes.",
        "distribution_mode": "hosted_protected",
        "access_tier": "free",
        "price_amount_minor": 0,
        "price_currency": "USD",
        "free_runs_per_month": 25,
        "current_version": "1.2.0",
        "input_schema": { "type": "object", "required": ["prompt"], "properties": { "prompt": { "type": "string" } } },
        "category": "Design",
        "category_slug": "design",
        "creator_name": "Ada Studio",
        "visibility": "public",
        "updated_at": "2026-09-14 10:12:03.511+00"
      }
    ]
  }
}

category, category_slug and creator_name are omitted when empty. There is no cursor pagination; a single page returns at most 100 skills.

#GET /v1/skills/{id-or-slug}

Returns one published hosted skill, public or unlisted, with the same fields as the catalog except category, category_slug and creator_name. An unknown or unavailable skill returns 404 skill_not_found.

#Marketplace content

#Run a skill

#POST /v1/skills/{id-or-slug}/run

Request body:

{
  "input": {
    "prompt": "Audit this signup form: email field without label, 12px placeholder text, red-only error state."
  }
}

• input is required and must be a JSON object.
• The request body is capped at 2 MiB, and the serialized input at the policy's max_input_bytes (64 KiB by default).
• input is checked against the skill's input schema: every required key must be present, and each declared top-level property must match its type (string, number or integer, boolean, object, array). Undeclared keys are allowed.

Response 200:

{
  "data": {
    "execution_id": "6f1d2c3b-8a9e-4f70-b1c2-d3e4f5a6b7c8",
    "skill_id": "0b6f8f9e-4c4d-4d0a-9d3e-2f1c8a7b6e5d",
    "skill_slug": "accessibility-audit",
    "version": "1.2.0",
    "output": "## Findings\n1. **Missing label (WCAG 1.3.1, 4.1.2)**: …",
    "usage": {
      "used": 3,
      "limit": 25,
      "reset_at": "2026-11-01T00:00:00Z",
      "access_tier": "free"
    }
  }
}

#Examples

curl:

curl -X POST "https://api.skillgild.com/v1/skills/accessibility-audit/run" \
  -H "Authorization: Bearer $SKILLGILD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8d9ba436-a430-44af-9d12-f1d3d4198227" \
  -d '{"input":{"prompt":"Audit this signup form"}}'

TypeScript (@skillgild/sdk):

import { SkillGildClient, SkillGildError } from "@skillgild/sdk";

const client = new SkillGildClient({ apiKey: process.env.SKILLGILD_API_KEY });

try {
  const run = await client.runSkill(
    "accessibility-audit",
    { prompt: "Audit this signup form" },
    { idempotencyKey: crypto.randomUUID() },
  );
  console.log(run.output, run.usage);
} catch (error) {
  if (error instanceof SkillGildError) console.error(error.status, error.code, error.message);
  else throw error;
}

Python (skillgild):

import os, uuid
from skillgild import SkillGildClient

client = SkillGildClient(api_key=os.environ["SKILLGILD_API_KEY"])
run = client.run_skill(
    "accessibility-audit",
    {"prompt": "Audit this signup form"},
    idempotency_key=str(uuid.uuid4()),
)
print(run["output"])

Go (github.com/skillgild/skillgild-dev/sdks/go/skillgild):

client, err := skillgild.NewClient("", skillgild.WithAPIKey(os.Getenv("SKILLGILD_API_KEY")))
if err != nil { return err }
run, err := client.RunSkill(ctx, "accessibility-audit", map[string]any{"prompt": "Audit this signup form"})
if err != nil { return err }
fmt.Println(run.Output)

Passing "" as the base URL uses the default, https://api.skillgild.com/v1.

CLI:

skillgild run accessibility-audit --input '{"prompt":"Audit this signup form"}' \
  --idempotency-key 8d9ba436-a430-44af-9d12-f1d3d4198227

MCP (what an agent sends to skillgild mcp):

{
  "name": "skillgild_run_skill",
  "arguments": {
    "skill_id": "accessibility-audit",
    "input": { "prompt": "Audit this signup form" }
  }
}

#What happens during a run

SkillGild performs these steps in order. The first failure stops the run and returns the matching error from Run errors.

1. Policy. Load runtime policy. If the global runtime is paused, return runtime_paused.
2. Input size. The input must be an object within max_input_bytes.
3. Idempotent replay. If the key matches a completed run, replay its stored response.
4. Resolve. Find the published hosted skill and its latest published version. The version must use prompt_pipeline.
5. Free tier. For a free skill, the free tier must not be paused.
6. Validate. Check the input against the input schema.
7. Rate limits: per user and version, per API key, and per client IP.
8. Claim idempotency key.
9. Provider health. The circuit breaker must be closed and the provider configured.
10. Reserve (all at once, atomically):
    • check the global and per-user concurrency caps;
    • check that the account is active;
    • for a paid skill, find the personal entitlement, then fall back to an organization entitlement;
    • check the monthly quota;
    • create the execution with status running and reserve one run.
11. Abuse protection. Record privacy-preserving abuse signals, never the input text.
12. Decrypt. Audit the access, then decrypt the version's private prompt.
13. Capacity. Reserve capacity against the platform's daily model budget.
14. Call the model, with a 90-second timeout and up to 4,096 output tokens.
15. Settle. Record usage and enforce the 1 MiB output limit.
16. Commit. Count the run, mark the execution completed, queue execution.completed webhooks, and store the encrypted idempotent response.

A failure after step 10 marks the execution failed, releases the reserved run and sends execution.failed webhooks. If the model provider fails repeatedly, SkillGild briefly pauses new runs to protect your allowance (503 provider_circuit_open).

#Idempotency

Send Idempotency-Key: <uuid> to make a retry safe. Keys are scoped to your user account and kept for 24 hours. A request is identified by the skill reference plus the exact input.

SkillGild never retries a model call on its own, because a call that timed out may still have been processed. To deliberately start another run, use a new key. The CLI's run command accepts --idempotency-key; the MCP tool does not send one.

#Run errors

#Default limits

These are the standard limits; enterprise limits can differ.

#Account and keys

Every endpoint in this section needs a session token, except the two marked otherwise.

#Device authorization (CLI login)

This is the flow skillgild login uses. A custom client can implement the same steps.

CLI                                 API                               Browser (signed in)
 │ POST /device-authorizations ───▶ │                                       │
 │ ◀── device_code, user_code ───── │                                       │
 │ open verification_uri ─────────────────────────────────────────────────▶ │
 │                                  │ ◀── POST /me/device-authorizations/approve {user_code}
 │ POST /device-authorizations/token every 5 s ──▶                          │
 │ ◀── { status: "authorized", access_token: "sg_live_…" }                  │

1. Start. POST /v1/device-authorizations needs no auth. The body { "device_name": "…", "client_type": "…" } is optional.

{
  "data": {
    "device_code": "…",
    "user_code": "ABCD-EFGH",
    "verification_uri": "https://skillgild.dev/connect/device?user_code=ABCD-EFGH",
    "expires_at": "2026-10-02T12:10:00Z",
    "interval_seconds": 5
  }
}

2. Approve. The signed-in user approves the code on the /connect/device page, which calls POST /v1/me/device-authorizations/approve with { "user_code": "ABCD-EFGH" }.

3. Poll. POST /v1/device-authorizations/token needs no auth. Send { "device_code": "…" } and repeat until it succeeds.

{ "data": { "status": "authorization_pending" } }

{ "data": { "status": "authorized", "access_token": "sg_live_…", "token_type": "Bearer", "key_prefix": "sg_live_1a2b3c4d" } }

The access token is returned exactly once. Codes expire after 10 minutes. Starting a flow is limited to 5 per 10 minutes per IP, and polling to 30 per minute.

#Webhooks

Get a signed notification when one of your runs finishes. These endpoints need a session token.

Delivery request:

POST https://your.app/hooks/skillgild
Content-Type: application/json
User-Agent: SkillGild-Webhooks/1.0
X-SkillGild-Event: execution.completed
X-SkillGild-Delivery: 3c1e…
X-SkillGild-Signature: t=1791028800,v1=5f2b…

{
  "id": "3c1e…",
  "type": "execution.completed",
  "created_at": "2026-10-02T12:00:00Z",
  "data": {
    "execution_id": "6f1d2c3b-…",
    "skill_id": "0b6f8f9e-…",
    "status": "completed",
    "error_code": null
  }
}

Payloads contain metadata only, never prompts, input or output. Each delivery has a 10-second timeout and does not follow redirects. The worker retries failed deliveries with backoff (up to 5 attempts by default); after that, use the replay endpoint.

Verify the signature. v1 is the hex HMAC-SHA256 of "{t}.{raw body}", keyed with your signing secret:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySkillGild(rawBody: string, header: string, secret: string, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(parts.v1, "hex"));
}

The timestamp tolerance check is your choice; SkillGild sends the current Unix time in t.

#Creator endpoints

All need a session token and an active creator profile. See Build and publish a skill for the full workflow.

#Other account endpoints

#SDK reference

The TypeScript, Python and Go SDKs are thin clients for the catalog and run endpoints. Every access decision stays on SkillGild's servers.

Search requests limit=100. Run methods require an API key.

#CLI and MCP reference

The MCP server (skillgild, version 0.1.0) exposes two tools:

Set SKILLGILD_API_URL to point the CLI and MCP server at a different API endpoint.