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

# Skills

> Read and author packaged instruction sets that compose into agent prompts.

Skills are instruction packages composed into agent prompts at dispatch time. A skill bundles guidance, optional files and allowed tools, and an activation mode (`always` or `on_demand`). Integrations browse the skill catalog and author workspace skills programmatically.

## Access

The skill catalog is platform-global: it has no org-unit home. `skills:read` lets a caller read every skill, and `skills:write` lets it create and update workspace skills that every caller holding `skills:read` can then read and assign. Only workspace skills are editable; a write to a `builtin`, `marketplace`, `clawhub` or `anthropic` skill is `422`. A created skill is always a workspace skill: a `source` in the request body is ignored.

## Resource shape

* `Skill` (list items, and the create and update responses): `id`, `skillId`, `name`, `description`, `version`, `status`, `owner`, `tags`, `emoji`, `skillType`, `source`, `quality`, `agentCount`, `assignedAgents` (`{ agentId, name }`), `createdAt`, `updatedAt`, `kind`, `enabled`, `activeVersionId`, `canaryVersionId`.
* `SkillDetail` (get): a `Skill` plus every version-defining field — `content`, `files`, `allowedTools`, `toolSets`, `defaultActivationMode`, `implicitActivation`, `maxInstructionTokens`, `priority`, `tierFloor`, `rubric` — and `fileRoles`, `inputModes`, `outputModes`, `requiresCapabilities`, `slashCommand` and the derived `determinism` profile.
* `SkillVersion` (listVersions): `versionId`, `version`, `status`, `synthesisTier`, `createdAt`.

An absent optional value is `null` (`[]` for `tags`, `{}` for `files` and `fileRoles`). The creator, principal, synthesis, embedding and usage fields are never returned, nor `quality.contentHash`; a rubric calibration example carries its `subjectHash`, never the subject.

## Versions and published workflows

Every change to a version-defining field mints an immutable version and moves `activeVersionId` to it (for an `active` skill). A change that touches only operational fields (`tags`, `emoji`, `owner`, `status`) mints nothing. A published workflow node pins the skill version that was active when it was published and keeps composing that version's content after the skill changes; an unpinned node composes the current head.

`status` (and `enabled`) are live controls outside version identity: setting a skill's `status` to anything but `active` removes it from every workflow at once, pinned or not. A status publishes or archives the skill, so an update that carries `status` also needs `skills:manage` at the platform scope, as the Console's publish and remove do. Without it the answer is `403 permission_denied` naming `skills:manage`, and nothing is written. Other fields still need only `skills:write`.

## Operations

Reads:

* `GET /api/v3/skills` — [listSkills](https://docs.gloo.com/forge/reference/http-api/skills/list.md) — page the catalog, oldest first
* `GET /api/v3/skills/{skillId}` — [getSkill](https://docs.gloo.com/forge/reference/http-api/skills/get.md) — fetch one skill by `skillId`
* `GET /api/v3/skills/{skillId}/versions` — [listSkillVersions](https://docs.gloo.com/forge/reference/http-api/skills/listVersions.md) — a skill's versions, newest first

Writes:

* `POST /api/v3/skills` — [createSkill](https://docs.gloo.com/forge/reference/http-api/skills/create.md) — author a workspace skill (`409` if the `skillId` exists)
* `PATCH /api/v3/skills/{skillId}` — [updateSkill](https://docs.gloo.com/forge/reference/http-api/skills/update.md) — patch a workspace skill named by `id` (its `skillId`)

Skill sets:

* `GET /api/v3/skill-sets` — [listSkillSets](https://docs.gloo.com/forge/reference/http-api/skills/listSets.md) — active skill sets and their member skills (`skills:read`)
* `POST /api/v3/skill-sets` — [createSkillSet](https://docs.gloo.com/forge/reference/http-api/skills/createSet.md) — create a workspace skill set (`skills:manage`)
* `PATCH /api/v3/skill-sets/{setId}` — [updateSkillSet](https://docs.gloo.com/forge/reference/http-api/skills/updateSet.md) — rename or redescribe a workspace skill set
* `DELETE /api/v3/skill-sets/{setId}` — [deleteSkillSet](https://docs.gloo.com/forge/reference/http-api/skills/deleteSet.md) — deprecate a workspace skill set
* `POST /api/v3/skill-sets/{setId}/members` — [addSkillSetMember](https://docs.gloo.com/forge/reference/http-api/skills/addSetMember.md) — add a skill to a set
* `DELETE /api/v3/skill-sets/{setId}/members/{skillId}` — [removeSkillSetMember](https://docs.gloo.com/forge/reference/http-api/skills/removeSetMember.md) — remove a skill from a set

A skill set groups skills for assignment: an agent holding a set composes every active member. The set writes need `skills:manage` at the platform scope, and a membership change reaches every holding agent at its next dispatch. They are reached from MCP through `forge_call_operation`.

## Paging

`limit` (1–100, default 50; a larger value is `400` `too_big`) and `cursor` page the catalog behind a unique keyset cursor, so a skill is never skipped or repeated across pages. Follow `meta.nextCursor` until `meta.hasMore` is `false`. `listVersions` pages a skill's versions newest first (`limit` 1–100, default 50): continue while `meta.hasMore` is `true`, passing `meta.nextCursor` as `cursor` with the same other parameters; a page may be short while more remain, and the list never answers `meta.partial`. A malformed `limit` is `400 Invalid: limit` on the catalog and `400 limit must be a positive integer` on `listVersions`; a malformed cursor is `400 Invalid cursor` on both.

## Retrying a write

Send an `Idempotency-Key` header with `create` or `update`. A same-key repeat of a completed write returns the recorded response with `Idempotency-Replayed: true` while the caller still holds `skills:write` (and `skills:manage`, when the repeated update carries a `status`), and never writes twice (see [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md)).

## Common workflow

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/skills" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "skillId": "issue-triage",
    "name": "Issue triage",
    "description": "Classify GitHub issues by severity and component",
    "content": "# Issue triage\n\nWhen given an issue body, ...",
    "defaultActivationMode": "always"
  }'

curl "$FORGE_BASE/api/v3/skills/issue-triage/versions" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

The Forge MCP server lists `forge_list_skills`; it reaches the other operations in its `skills` tool group through `forge_call_operation` with operationId `getSkill`, `listSkillVersions`, `createSkill` and `updateSkill`.

## Related

* [Skills overview](https://docs.gloo.com/forge/build/author-a-skill.md) — conceptual background on the skills system
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.