Skills

A skill is a saved, reusable ask. A person writes it one time in roasOS and gives it a name. Your software then runs it by its id, or by its slug.

A skill run is an agent run. It uses the same caps, the same approvals, and the same read path as POST /v1/agent/completions.

Your workspace has two kinds of skill. A workspace skill is one that a person in your workspace wrote. A pack skill is one that roasOS ships. Both run through the same path. Refer to The roasOS skill pack.

List your skills

curl "https://api.roasos.com/v1/skills?limit=20" \
  -H "Authorization: Bearer roasos_sk_..."

{
  "data": [
    {
      "id": "7c2a3f10-...",
      "slug": null,
      "name": "Weekly hook test",
      "description": "Three new hooks for the best ad of last week.",
      "prompt": "Find my best performing ad from the last 7 days. Write three new hooks for it. Render the first frame of each hook.",
      "use_count": 12,
      "pack_version": null,
      "created_at": "2026-07-02T09:14:00.000Z",
      "updated_at": "2026-08-18T08:02:11.000Z"
    },
    {
      "id": "855acde9-c801-4076-97cd-b08de3985705",
      "slug": "roasos:remix-ad",
      "name": "Remix an ad",
      "description": "Recreate a reference ad for your own product.",
      "prompt": "…the prompt that roasOS ships for this skill…",
      "use_count": 4,
      "pack_version": 1,
      "created_at": "2026-08-23T00:00:00.000Z",
      "updated_at": "2026-08-23T00:00:00.000Z"
    }
  ],
  "meta": { "has_more": false }
}

The list holds the skills of your workspace and the skills of the roasOS pack. slug tells the two apart: a workspace skill has null, and a pack skill has its roasos: name. pack_version follows the same rule, and it is null on a workspace skill.

This page shortens the prompt of a pack skill in its examples. The API always answers with the whole text.

The list gives one page. Send the cursor value from meta to read the next page. Refer to Pagination.

Read one skill

curl https://api.roasos.com/v1/skills/7c2a3f10-... \
  -H "Authorization: Bearer roasos_sk_..."

The answer holds the same object under data. Read prompt. It is the exact text that the run uses.

A pack skill answers to its slug as well as to its id.

curl https://api.roasos.com/v1/skills/roasos:remix-ad \
  -H "Authorization: Bearer roasos_sk_..."

A skill in a different workspace returns 404.

Run a skill

POST /v1/skills/{id}/runs starts the run. The body states no text, because the prompt of the skill is the text. The body states the money only.

Quote first. Set quote_only to true.

curl -X POST https://api.roasos.com/v1/skills/7c2a3f10-.../runs \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Idempotency-Key: weekly-hook-test-2026-08-21" \
  -H "Content-Type: application/json" \
  -d '{
    "max_credits": 20,
    "generation_spend_cap_credits": 30,
    "quote_only": true
  }'

{
  "data": {
    "schema_version": "agent-run@1",
    "kind": "agent_run",
    "id": "9e51b704-...",
    "trigger": "skill",
    "skill_id": "7c2a3f10-...",
    "conversation_id": null,
    "status": "quoted",
    "max_credits": 20,
    "generation_spend_cap_credits": 30,
    "credits_reserved": 0,
    "credits_max": 50,
    "pricing_version": "agent-token-pricing@2026-10-04.v3",
    "quote_id": "5a7d9c02-...",
    "expires_at": "2026-08-21T09:12:40.000Z",
    "authorization": { "status": "auto_approved" },
    "created_at": "2026-08-21T09:02:40.000Z",
    "updated_at": "2026-08-21T09:02:40.000Z"
  }
}

Then confirm with the quote_id and the same idempotency key. The answer is 202.

curl -X POST https://api.roasos.com/v1/skills/7c2a3f10-.../runs \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Idempotency-Key: weekly-hook-test-2026-08-21" \
  -H "Content-Type: application/json" \
  -d '{
    "max_credits": 20,
    "generation_spend_cap_credits": 30,
    "quote_id": "5a7d9c02-..."
  }'

Read the run at /v1/agent-runs/9e51b704-.... The trigger is skill, and skill_id names the skill. Refer to Runs.

The body can omit both caps. The run then uses the defaults: 25 credits for the thinking, and 0 credits for paid work. A run with a cap of 0 leaves each paid action as an approval for a person.

The body must still carry quote_only or a quote_id. roasOS rejects a paid call that carries neither, exactly as it does on every other paid path.

roasOS adds 1 to use_count after the run starts. A typed workflow door counts too: a run of POST /v1/workflows/remix is a use of roasos:remix-ad.

The roasOS skill pack

roasOS ships twelve skills. Every workspace has them from the first day. No workspace can change them.

A pack skill is a skill, not a second kind of object. It has the same fields, the same run path, and the same meter as a skill that your workspace wrote.

One card, and eight quotes on it

A pack skill puts the whole price of a step on one approval card. One card carries at most eight quotes, so a step that renders a set stops at eight.

roasos:statics-factory therefore makes 1 to 8 static ads in one call, and a request for a ninth answers 400 validation_error. roasos:remix-ad fans out at most two variants of one board for the same reason. Refer to Spend caps and approvals.

Address a pack skill by slug or by id

The path takes both forms.

curl -X POST https://api.roasos.com/v1/skills/roasos:remix-ad/runs \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Idempotency-Key: remix-glow-serum-001" \
  -H "Content-Type: application/json" \
  -d '{ "generation_spend_cap_credits": 120, "quote_only": true }'

Use the slug. It is stable, and a person can write it from memory. The UUID answers the same run.

Any other value answers 400 validation_error. A slug has the form roasos: and 1 to 60 lower-case letters, digits or hyphens. Only roasOS writes a slug.

A pack skill is read-only

No workspace can edit a pack skill, and no workspace can delete one. The pack belongs to no workspace, and every write path in roasOS filters on the workspace. There is no API operation that changes a skill of either kind.

Copy the prompt into a skill of your own to make a version you control.

The pack has a version

pack_version is the revision of one prompt, and not the revision of the whole pack. roasOS raises the number of a skill when it rewrites that skill's prompt. Two of the nine skills are still at 1, roasos:localize-ad is at 2, roasos:recast-actor is at 3, roasos:animated-story is at 5, and the four skills revised in the 2026-08-31 alignment pass are at 6. The prompt field is always the exact text that the next run uses. Read it when your software depends on the steps.

use_count on a pack skill counts the runs of every workspace, because the pack is one shared record. use_count on your own skill counts your workspace only.

The fields of a skill

A skill holds no model, no tool list, and no input schema. The agent chooses the tools and the models for each run, exactly as it does for an ask.

Errors

A skill run uses the same door as an ask, so it gives the same answers. Refer to Errors at the door.

From an agent

Three MCP tools cover this page: roasos_list_skills, roasos_get_skill, and roasos_run_skill. roasos_run_skill obeys the same quote rule as every paid tool. It takes a slug as well as an id, so an agent can run roasos:remix-ad without a lookup. Refer to Connect an AI agent (MCP).