Skills

Overview

/v1/skills manages account-level Agent Brain skills — the same catalog as agent.creao.ai/skills. These are not a personal agent’s skill_content, and they are not workspace files. After you install or enable a skill, it applies to the same CREAO account in chat / Agent Brain and in CREAO CLI runs. /v1/runs does not accept a per-run skill list. A run therefore sees enabled custom skills plus the full built-in catalog — not only the subset enabled in chat. CREAO CLI runs that use agent_id still also follow that agent’s own SKILL.md. Public identifiers use skill_id (blog-post, custom-weekly-digest), not the custom-skill UUID. Built-in skills have no UUID.

Agent skill files stay on /v1/agents/{agent_id}/files. That API is list, download, and delete only — it does not upload a skill folder.

Install a skill

v1 accepts two sources. Reinstalling the same custom name upserts: 201 for a new skill, 200 when it already exists. Skills are enabled by default. A 200 or 201 means the skill row and enabledSkillIds are committed. Sandbox file materialization continues in the background. A chat or /v1/runs request started in the same second might not see the new files yet; a later run will.

From GitHub

curl -X POST https://developer.creao.ai/v1/skills \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "github",
    "source_url": "https://github.com/acme/weekly-digest",
    "enabled": true
  }'

From SKILL.md content

curl -X POST https://developer.creao.ai/v1/skills \
  -H "Authorization: Bearer cr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "content",
    "content": "---\nname: weekly-digest\n---\n# Weekly Digest\n",
    "files": { "scripts/run.py": "print(\"ok\")" },
    "tags": ["ops"],
    "enabled": true
  }'

{
  "id": "77777777-7777-4777-8777-777777777777",
  "skill_id": "custom-weekly-digest",
  "kind": "custom",
  "name": "weekly-digest",
  "display_name": "weekly-digest",
  "description": "Write a weekly digest",
  "enabled": true,
  "core": false,
  "source_url": null,
  "tags": ["ops"],
  "created_at": "2026-08-18T00:00:00.000Z",
  "updated_at": "2026-08-18T00:00:00.000Z",
  "content": "---\nname: weekly-digest\n---\n# Weekly Digest\n",
  "files": { "scripts/run.py": "print(\"ok\")" }
}

Rules:

Custom skill_id is custom-{name}
name must be a valid skill name (lowercase letters, numbers, and hyphens)
A name that collides with a built-in skill is rejected
SKILL.md is limited to 256 KB; supporting files total 5 MB
GitHub accepts a single repository URL (no ZIP, Discover, or batch import)

List skills

curl "https://developer.creao.ai/v1/skills?kind=custom&enabled=true" \
  -H "Authorization: Bearer cr_sk_your_key_here"

The listing includes optional built-in skills and non-deleted custom skills. Core built-ins are omitted. Responses include metadata and enabled, not skill bodies. This endpoint is not paginated. Optional query parameters: kind=builtin|custom and enabled=true|false.

Get a skill

curl https://developer.creao.ai/v1/skills/custom-weekly-digest \
  -H "Authorization: Bearer cr_sk_your_key_here"

Detail responses include content. Custom skills also include files. Core built-ins return SKILL_NOT_FOUND.

Enable or disable a skill

curl -X POST https://developer.creao.ai/v1/skills/custom-weekly-digest/enable \
  -H "Authorization: Bearer cr_sk_your_key_here"

curl -X POST https://developer.creao.ai/v1/skills/custom-weekly-digest/disable \
  -H "Authorization: Bearer cr_sk_your_key_here"

Disable removes the skill from enabledSkillIds and unmounts its files. It does not delete the custom-skill row. There is no PATCH or DELETE. Already-enabled or already-disabled skills succeed idempotently. HTTP 200 from enable or disable means the enabledSkillIds change is committed. Volume/S3 file materialization or unmount continues in the background. Optional built-ins and custom skills can be toggled. Core built-ins return SKILL_ALWAYS_ON.

Refresh a GitHub skill

curl -X POST https://developer.creao.ai/v1/skills/custom-weekly-digest/refresh \
  -H "Authorization: Bearer cr_sk_your_key_here"

Refresh re-fetches a GitHub-sourced custom skill. Content-installed skills and built-ins return SKILL_NOT_REFRESHABLE.

Errors

Code	When
`SKILL_NOT_FOUND`	No matching optional built-in or custom skill, or the id is a core built-in on GET
`SKILL_NAME_INVALID`	The skill name or `skill_id` is empty, too long, or not a valid identifier
`SKILL_NAME_CONFLICT`	The custom name collides with a built-in skill
`SKILL_ALWAYS_ON`	A core built-in cannot be enabled or disabled
`SKILL_NOT_REFRESHABLE`	The skill is not a GitHub-sourced custom skill
`INVALID_GITHUB_URL`	`source_url` is missing or is not a GitHub repository URL
`SKILL_CONTENT_TOO_LARGE`	`SKILL.md` exceeds 256 KB or supporting files exceed 5 MB
`INVALID_INPUT`	Missing required fields or unknown field

See also the OpenAPI operations under Skills.

Get Started

Agents

Agent Memory

Agent Files

Product Profile

Agent Runs

Super Agent

Account

Workspaces

Workspace Files

Secrets

Concepts

Skills

Overview

Install a skill

From GitHub

From SKILL.md content

List skills

Get a skill

Enable or disable a skill

Refresh a GitHub skill

Errors

​Overview

​Install a skill

​From GitHub

​From SKILL.md content

​List skills

​Get a skill

​Enable or disable a skill

​Refresh a GitHub skill

​Errors

Overview

Install a skill

From GitHub

From SKILL.md content

List skills

Get a skill

Enable or disable a skill

Refresh a GitHub skill

Errors