> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creao.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Install, list, and enable account-level Agent Brain skills through the Developer API.

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

<Note>
  Agent skill files stay on [`/v1/agents/{agent_id}/files`](/developer-api/agent-files). That API is list, download, and delete only — it does not upload a skill folder.
</Note>

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

```bash theme={null}
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

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/developer-api/skills/list-skills).