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 chat / Agent Brain for the same CREAO account. Developer API runs that use agent_id keep using that agent’s own SKILL.md. /v1/runs does not inject these skills. 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.

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. 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

Runs

Models

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