# Skills

> SKILL.md instruction bundles the workspace's agents load as context: list, create, edit files, validate, publish, toggle, and revert.

Source: https://docs.generalinput.com/api/skills



A skill is a `SKILL.md` bundle in the Agent Skills format: frontmatter (`name`, `description`) plus instructions, with optional `scripts/`, `references/`, and `assets/`. It is never executed. Agents load it by name when its description matches the task.

<Access scope="skills:manage" />

Skill ids are `skl_…`. Two ways to change files: [save one file](/api/skills/save-file) inline for small edits, or push a whole bundle through a [presigned upload](/api/skills/bundle-upload-url) then [validate](/api/skills/validate) and [publish](/api/skills/publish), which is how the CLI works and the only way to carry binary assets.

## Concurrency [#concurrency]

Skills carry a `version` counter. Writes that race another writer answer `409`; refetch and retry.

## Endpoints [#endpoints]

| Endpoint                                                                       | Does                                       |
| ------------------------------------------------------------------------------ | ------------------------------------------ |
| [`GET /v1/skills`](/api/skills/list)                                           | Workspace skills plus the platform catalog |
| [`POST /v1/skills`](/api/skills/create)                                        | Create a draft                             |
| [`GET /v1/skills/:id`](/api/skills/get)                                        | Detail                                     |
| [`PATCH /v1/skills/:id`](/api/skills/update)                                   | Rename or change the description           |
| [`DELETE /v1/skills/:id`](/api/skills/archive)                                 | Archive                                    |
| [`PATCH /v1/skills/:id/enabled`](/api/skills/set-enabled)                      | Enable or disable                          |
| [`GET /v1/skills/platform/:name`](/api/skills/get-platform-skill)              | A platform skill's files                   |
| [`GET /v1/skills/:id/files`](/api/skills/get-files)                            | The published bundle's files               |
| [`PUT /v1/skills/:id/files`](/api/skills/save-file)                            | Save one file and republish                |
| [`GET /v1/skills/:id/bundle-url`](/api/skills/bundle-url)                      | Presigned download of the live bundle      |
| [`POST /v1/skills/:id/bundle-upload-url`](/api/skills/bundle-upload-url)       | Presigned upload for a staged bundle       |
| [`POST /v1/skills/:id/validate`](/api/skills/validate)                         | Validate a staged bundle                   |
| [`POST /v1/skills/:id/publish`](/api/skills/publish)                           | Publish a staged bundle                    |
| [`GET /v1/skills/:id/versions`](/api/skills/list-versions)                     | Version history                            |
| [`POST /v1/skills/:id/versions/:versionId/revert`](/api/skills/revert-version) | Revert to a version                        |