Skill Studio — API

export API="https://api.skillsafe.ai/v1/app-api"
export SKILLSAFE_TOKEN="YOUR_TOKEN"      # see step 1

# every call looks like:
#   curl -s "$API/..." -H "Authorization: Bearer $SKILLSAFE_TOKEN" [-d '{json}']
# jq is used below to pull fields out of the {"data": ...} envelope

import json, os, requests

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = os.environ.get("SKILLSAFE_TOKEN", "YOUR_TOKEN")  # see step 1

def api(method, path, body=None, **headers):
    res = requests.request(method, API + path, json=body,
                           headers={"Authorization": f"Bearer {TOKEN}", **headers})
    payload = res.json()
    if not res.ok:
        raise RuntimeError(payload.get("error", {}).get("message", res.reason))
    return payload["data"]

// Node 18+ (built-in fetch)
const API = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN"; // see step 1 — read it from your shell environment in real code

async function api(method, path, body, extraHeaders = {}) {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", ...extraHeaders },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? res.statusText);
  return json.data;
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

const API = "https://api.skillsafe.ai/v1/app-api"

var token = os.Getenv("SKILLSAFE_TOKEN") // see step 1

func call(method, path string, body, out any, extra map[string]string) error {
	var buf bytes.Buffer
	if body != nil {
		json.NewEncoder(&buf).Encode(body)
	}
	req, _ := http.NewRequest(method, API+path, &buf)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	for k, v := range extra {
		req.Header.Set(k, v)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	var env struct {
		Data  json.RawMessage `json:"data"`
		Error *struct{ Message string } `json:"error"`
	}
	json.NewDecoder(res.Body).Decode(&env)
	if env.Error != nil {
		return fmt.Errorf("%s", env.Error.Message)
	}
	if out != nil {
		return json.Unmarshal(env.Data, out)
	}
	return nil
}

import java.net.URI;
import java.net.http.*;
import java.util.Map;

class SkillSafe {
  static final String API = "https://api.skillsafe.ai/v1/app-api";
  static final String TOKEN = System.getenv().getOrDefault("SKILLSAFE_TOKEN", "YOUR_TOKEN");
  static final HttpClient CLIENT = HttpClient.newHttpClient();

  static String api(String method, String path, String jsonBody, Map<String,String> extra)
      throws Exception {
    HttpRequest.Builder b = HttpRequest.newBuilder(URI.create(API + path))
        .header("Authorization", "Bearer " + TOKEN)
        .header("Content-Type", "application/json")
        .method(method, jsonBody == null
            ? HttpRequest.BodyPublishers.noBody()
            : HttpRequest.BodyPublishers.ofString(jsonBody));
    if (extra != null) extra.forEach(b::header);
    HttpResponse<String> res = CLIENT.send(b.build(), HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() >= 400) throw new RuntimeException(res.body());
    return res.body();   // {"data": ...} — unwrap with your JSON library
  }
}

require "json"
require "net/http"
require "uri"

API   = "https://api.skillsafe.ai/v1/app-api"
TOKEN = ENV.fetch("SKILLSAFE_TOKEN", "YOUR_TOKEN")   # see step 1

def api(method, path, body = nil, extra = {})
  uri = URI(API + path)
  klass = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post }.fetch(method)
  req = klass.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"]  = "application/json"
  extra.each { |k, v| req[k] = v }
  req.body = JSON.dump(body) if body
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  payload = JSON.parse(res.body)
  raise payload.dig("error", "message").to_s unless res.is_a?(Net::HTTPSuccess)
  payload["data"]
end

<?php
const API = "https://api.skillsafe.ai/v1/app-api";
$TOKEN = getenv("SKILLSAFE_TOKEN") ?: "YOUR_TOKEN";   // see step 1

function api(string $method, string $path, ?array $body = null, array $extra = []): array {
    global $TOKEN;
    $headers = ["Authorization: Bearer $TOKEN", "Content-Type: application/json"];
    foreach ($extra as $k => $v) { $headers[] = "$k: $v"; }
    $ch = curl_init(API . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
    ]);
    if ($body !== null) { curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body)); }
    $raw  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $json = json_decode($raw, true);
    if ($code >= 400) { throw new RuntimeException($json["error"]["message"] ?? "http $code"); }
    return $json["data"];
}

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

static class SkillSafe {
    const string API = "https://api.skillsafe.ai/v1/app-api";
    static readonly string Token =
        Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN") ?? "YOUR_TOKEN";
    static readonly HttpClient Http = new();

    public static async Task<JsonElement> ApiAsync(
        HttpMethod method, string path, object? body = null,
        IDictionary<string, string>? extra = null) {
        var req = new HttpRequestMessage(method, API + path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
        if (body is not null)
            req.Content = new StringContent(JsonSerializer.Serialize(body),
                                            Encoding.UTF8, "application/json");
        if (extra is not null)
            foreach (var kv in extra) req.Headers.TryAddWithoutValidation(kv.Key, kv.Value);
        var res = await Http.SendAsync(req);
        var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
        if (!res.IsSuccessStatusCode)
            throw new Exception(doc.RootElement.GetProperty("error").GetProperty("message").GetString());
        return doc.RootElement.GetProperty("data");
    }
}

curl -s "$API/guest" -H "Content-Type: application/json" \
  -d '{"slug":"skill-studio"}' | jq -r '.data.token'
# export SKILLSAFE_TOKEN="the value printed above"

guest = requests.post(API + "/guest", json={"slug": "skill-studio"}).json()["data"]
TOKEN = guest["token"]        # replaces the placeholder from step 0
print(guest["guest_id"], guest["token"][:8] + "...")

const guestRes = await fetch(`${API}/guest`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ slug: "skill-studio" }),
});
const guest = (await guestRes.json()).data;   // { token, guest_id, ... }

var guest struct {
	Token   string `json:"token"`
	GuestID string `json:"guest_id"`
}
// /guest is the one call that needs no token yet.
if err := call("POST", "/guest", map[string]string{"slug": "skill-studio"}, &guest, nil); err != nil {
	panic(err)
}
token = guest.Token

String guest = SkillSafe.api("POST", "/guest", "{\"slug\":\"skill-studio\"}", null);
// guest -> {"data":{"token":"...","guest_id":"..."}}
// Pull data.token with your JSON library and use it as the bearer token.

guest = api("POST", "/guest", { "slug" => "skill-studio" })
token = guest["token"]     # use in place of the step-0 placeholder
puts guest["guest_id"]

$guest = api("POST", "/guest", ["slug" => "skill-studio"]);
$TOKEN = $guest["token"];          // replaces the step-0 placeholder
echo $guest["guest_id"], PHP_EOL;

var guest = await SkillSafe.ApiAsync(HttpMethod.Post, "/guest",
    new { slug = "skill-studio" });
var token = guest.GetProperty("token").GetString();
Console.WriteLine(guest.GetProperty("guest_id").GetString());

curl -s "$API/me" -H "Authorization: Bearer $SKILLSAFE_TOKEN" | jq '.data'
# { "subject_type": "user", "subject_id": "...", "credits": 250000 }

me = api("GET", "/me")
print(me["subject_type"], me["credits"], "credits")

const me = await api("GET", "/me");
console.log(me.subject_type, me.credits, "credits");

var me struct {
	SubjectType string `json:"subject_type"`
	Credits     int64  `json:"credits"`
}
if err := call("GET", "/me", nil, &me, nil); err != nil {
	panic(err)
}
fmt.Println(me.SubjectType, me.Credits, "credits")

String me = SkillSafe.api("GET", "/me", null, null);
System.out.println(me);   // {"data":{"subject_type":"user","credits":250000,...}}

me = api("GET", "/me")
puts "#{me["subject_type"]} — #{me["credits"]} credits"

$me = api("GET", "/me");
echo $me["subject_type"], " — ", $me["credits"], " credits", PHP_EOL;

var me = await SkillSafe.ApiAsync(HttpMethod.Get, "/me");
Console.WriteLine($"{me.GetProperty("subject_type").GetString()} — " +
                  $"{me.GetProperty("credits").GetInt64()} credits");

cat > input.json <<'JSON'
{
  "brief": "We ship a Postgres billing service and migrations are the scariest part of every deploy. I want a skill that makes the coding agent review migrations before merge. Three house rules: every migration is a numbered up/down pair and a missing down file is an automatic reject; tables are plural snake_case, FK columns end in _id, indexes are idx__; anything rewriting a table over a million rows ships across two deploys. I cannot share our full style guide or the real schema.",
  "triggers": "Review this migration before I merge it\nIs this ALTER TABLE going to lock the orders table\nWrite a rollback note for migration 0142",
  "name": "postgres-migration-reviewer",
  "existing": "",
  "mode": "Create"
}
JSON

curl -s "$API/estimate" -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" -d @input.json | jq '.data'
# { "hold_credits": 1595, "min_credits": 167,
#   "model": "gpt-5.6-terra", "model_alias": "gpt-terra", "markup_bps": 1000 }
payload = {
    "brief": "We ship a Postgres billing service and migrations are the scariest part of "
             "every deploy. I want a skill that makes the coding agent review migrations "
             "before merge. Three house rules: numbered up/down pairs (a missing down file "
             "is an automatic reject); plural snake_case tables, _id foreign keys, "
             "idx__ indexes; anything rewriting a table over a million rows "
             "ships across two deploys. I cannot share our full style guide or the schema.",
    "triggers": "Review this migration before I merge it\n"
                "Is this ALTER TABLE going to lock the orders table",
    "name": "postgres-migration-reviewer",
    "existing": "",
    "mode": "Create",
}

est = api("POST", "/estimate", payload)
print(est["hold_credits"], "reserved on", est["model_alias"], "->", est["model"])
if api("GET", "/me")["credits"] < est["min_credits"]:
    raise SystemExit("top up before running")
const payload = {
  brief: "We ship a Postgres billing service and migrations are the scariest part of every " +
         "deploy. I want a skill that makes the coding agent review migrations before merge. " +
         "Three house rules: numbered up/down pairs; plural snake_case tables with _id foreign " +
         "keys; anything rewriting a table over a million rows ships across two deploys.",
  triggers: "Review this migration before I merge it\nIs this ALTER TABLE going to lock orders",
  name: "postgres-migration-reviewer",
  existing: "",
  mode: "Create",
};

const est = await api("POST", "/estimate", payload);
console.log(`${est.hold_credits} reserved on ${est.model_alias} -> ${est.model}`);
payload := map[string]any{
	"brief":    "We ship a Postgres billing service and migrations are the scariest part of every deploy. I want a skill that reviews migrations before merge...",
	"triggers": "Review this migration before I merge it",
	"name":     "postgres-migration-reviewer",
	"existing": "",
	"mode":     "Create",
}

var est struct {
	HoldCredits int64  `json:"hold_credits"`
	MinCredits  int64  `json:"min_credits"`
	Model       string `json:"model"`
	ModelAlias  string `json:"model_alias"`
}
if err := call("POST", "/estimate", payload, &est, nil); err != nil {
	panic(err)
}
fmt.Printf("%d reserved on %s -> %s\n", est.HoldCredits, est.ModelAlias, est.Model)
String payload = """
  {"brief":"We ship a Postgres billing service and migrations are the scariest part of every deploy. I want a skill that reviews migrations before merge...",
   "triggers":"Review this migration before I merge it",
   "name":"postgres-migration-reviewer",
   "existing":"",
   "mode":"Create"}
  """;

String est = SkillSafe.api("POST", "/estimate", payload, null);
System.out.println(est);   // data.hold_credits, data.min_credits, data.model, data.model_alias
payload = {
  "brief"    => "We ship a Postgres billing service and migrations are the scariest part of " \
                "every deploy. I want a skill that reviews migrations before merge...",
  "triggers" => "Review this migration before I merge it",
  "name"     => "postgres-migration-reviewer",
  "existing" => "",
  "mode"     => "Create"
}

est = api("POST", "/estimate", payload)
puts "#{est["hold_credits"]} reserved on #{est["model_alias"]} -> #{est["model"]}"
$payload = [
    "brief"    => "We ship a Postgres billing service and migrations are the scariest part "
                . "of every deploy. I want a skill that reviews migrations before merge...",
    "triggers" => "Review this migration before I merge it",
    "name"     => "postgres-migration-reviewer",
    "existing" => "",
    "mode"     => "Create",
];

$est = api("POST", "/estimate", $payload);
printf("%d reserved on %s -> %s\n", $est["hold_credits"], $est["model_alias"], $est["model"]);
var payload = new {
    brief = "We ship a Postgres billing service and migrations are the scariest part of every " +
            "deploy. I want a skill that reviews migrations before merge...",
    triggers = "Review this migration before I merge it",
    name = "postgres-migration-reviewer",
    existing = "",
    mode = "Create"
};

var est = await SkillSafe.ApiAsync(HttpMethod.Post, "/estimate", payload);
Console.WriteLine($"{est.GetProperty("hold_credits").GetInt64()} reserved on " +
                  $"{est.GetProperty("model_alias").GetString()}");

      
Step 4 — Write the skill
      
POST /run
      
GET /jobs/{job_id}
      

        Metered. The body is the input object itself. The call returns a
        job_id; poll /jobs/{job_id} every 1–2 seconds until
        status is succeeded or failed, then read the text
        from output.output. Always send an Idempotency-Key: derive it from
        a hash of the input plus an attempt counter so a dropped connection, or a retry after a
        malformed reply, can never be billed twice.
      
      

JOB_ID=$(curl -s "$API/run" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: skill-studio:9f2ab13c:a1" \
  -d @input.json | jq -r '.data.job_id')

while :; do
  JOB=$(curl -s "$API/jobs/$JOB_ID" -H "Authorization: Bearer $SKILLSAFE_TOKEN")
  STATUS=$(echo "$JOB" | jq -r '.data.status')
  [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done

echo "$JOB" | jq -r '.data.output.output' > SKILL.md
echo "$JOB" | jq -r '.data.charged_credits'
import hashlib, time

def idem(payload, attempt=1):
    basis = "".join(str(payload.get(k, "")) for k in
                    ("brief", "triggers", "name", "existing", "mode"))
    return f"skill-studio:{hashlib.sha256(basis.encode()).hexdigest()[:12]}:a{attempt}"

job_id = api("POST", "/run", payload, **{"Idempotency-Key": idem(payload)})["job_id"]

while True:
    job = api("GET", f"/jobs/{job_id}")
    if job["status"] in ("succeeded", "failed"):
        break
    time.sleep(2)

if job["status"] == "failed":
    raise SystemExit(job.get("error", "run failed"))

text = job["output"]["output"]
open("SKILL.md", "w").write(text)
print(job["charged_credits"], "credits charged")
import { createHash } from "node:crypto";
import { writeFile } from "node:fs/promises";

const idem = (p, attempt = 1) => {
  const basis = ["brief", "triggers", "name", "existing", "mode"].map((k) => p[k] ?? "").join("");
  return `skill-studio:${createHash("sha256").update(basis).digest("hex").slice(0, 12)}:a${attempt}`;
};

const { job_id } = await api("POST", "/run", payload, { "Idempotency-Key": idem(payload) });

let job;
for (;;) {
  job = await api("GET", `/jobs/${job_id}`);
  if (job.status === "succeeded" || job.status === "failed") break;
  await new Promise((r) => setTimeout(r, 2000));
}
if (job.status === "failed") throw new Error(job.error ?? "run failed");

await writeFile("SKILL.md", job.output.output);
console.log(job.charged_credits, "credits charged");
var started struct{ JobID string `json:"job_id"` }
headers := map[string]string{"Idempotency-Key": "skill-studio:9f2ab13c:a1"}
if err := call("POST", "/run", payload, &started, headers); err != nil {
	panic(err)
}

var job struct {
	Status         string `json:"status"`
	ChargedCredits int64  `json:"charged_credits"`
	Output         struct {
		Output string `json:"output"`
	} `json:"output"`
}
for {
	if err := call("GET", "/jobs/"+started.JobID, nil, &job, nil); err != nil {
		panic(err)
	}
	if job.Status == "succeeded" || job.Status == "failed" {
		break
	}
	time.Sleep(2 * time.Second)
}
os.WriteFile("SKILL.md", []byte(job.Output.Output), 0o644)
fmt.Println(job.ChargedCredits, "credits charged")
String started = SkillSafe.api("POST", "/run", payload,
    java.util.Map.of("Idempotency-Key", "skill-studio:9f2ab13c:a1"));
String jobId = /* data.job_id via your JSON library */ "";

String job;
while (true) {
  job = SkillSafe.api("GET", "/jobs/" + jobId, null, null);
  // read data.status; break on "succeeded" or "failed"
  if (job.contains("\"status\":\"succeeded\"") || job.contains("\"status\":\"failed\"")) break;
  Thread.sleep(2000);
}
// The skill text is data.output.output — write it to SKILL.md.
System.out.println(job);
require "digest"

def idem(payload, attempt = 1)
  basis = %w[brief triggers name existing mode].map { |k| payload[k].to_s }.join
  "skill-studio:#{Digest::SHA256.hexdigest(basis)[0, 12]}:a#{attempt}"
end

started = api("POST", "/run", payload, { "Idempotency-Key" => idem(payload) })

job = nil
loop do
  job = api("GET", "/jobs/#{started["job_id"]}")
  break if %w[succeeded failed].include?(job["status"])
  sleep 2
end
abort(job["error"].to_s) if job["status"] == "failed"

File.write("SKILL.md", job["output"]["output"])
puts "#{job["charged_credits"]} credits charged"
function idem(array $payload, int $attempt = 1): string {
    $basis = "";
    foreach (["brief", "triggers", "name", "existing", "mode"] as $k) {
        $basis .= (string)($payload[$k] ?? "");
    }
    return "skill-studio:" . substr(hash("sha256", $basis), 0, 12) . ":a$attempt";
}

$started = api("POST", "/run", $payload, ["Idempotency-Key" => idem($payload)]);

do {
    sleep(2);
    $job = api("GET", "/jobs/" . $started["job_id"]);
} while (!in_array($job["status"], ["succeeded", "failed"], true));

if ($job["status"] === "failed") { throw new RuntimeException($job["error"] ?? "run failed"); }

file_put_contents("SKILL.md", $job["output"]["output"]);
echo $job["charged_credits"], " credits charged", PHP_EOL;
using System.Security.Cryptography;

static string Idem(object p, int attempt = 1) {
    var basis = JsonSerializer.Serialize(p);
    var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(basis)))[..12];
    return $"skill-studio:{hash.ToLowerInvariant()}:a{attempt}";
}

var started = await SkillSafe.ApiAsync(HttpMethod.Post, "/run", payload,
    new Dictionary<string, string> { ["Idempotency-Key"] = Idem(payload) });
var jobId = started.GetProperty("job_id").GetString();

JsonElement job;
while (true) {
    job = await SkillSafe.ApiAsync(HttpMethod.Get, $"/jobs/{jobId}");
    var status = job.GetProperty("status").GetString();
    if (status is "succeeded" or "failed") break;
    await Task.Delay(2000);
}
await File.WriteAllTextAsync("SKILL.md",
    job.GetProperty("output").GetProperty("output").GetString());
      
      

        If truncated comes back true, the reply hit the run's output cap
        because the balance sat between min_credits and hold_credits.
        Treat that text as incomplete — the later sections (RESOURCES:,
        REVIEW:) are the ones that go missing — rather than presenting it as a
        finished skill.
      
    

      
Step 5 — Stream it instead
      
POST /run-stream
      

        Same body, same billing, same Idempotency-Key, but the response is
        text/event-stream and the sections arrive as they are written. This is what the
        browser app uses, and it is what lets a client show real progress: the section markers
        (FRONTMATTER:, SKILL:, RESOURCES:,
        REVIEW:) arrive in order, so each one is a genuine progress signal rather than
        a spinner.
      
      

        

          
Event
Data
Use
          
job
{job_id, status}
Sent once, when the job is accepted — show "starting".
          
delta
{text}
A fragment of the reply. Append it; watch for the section markers.
          
done
{job_id, status, charged_credits, truncated, output}
The final, authoritative result — read the skill from output.output rather than trusting concatenated deltas, and the settled price from charged_credits.
          
error
{code, message, job_id}
The run failed. Anything already appended from delta events is still worth keeping.