# Skills

Skills and their versions: upload a SKILL.md bundle, add versions that become the latest and read the library's custom and Anthropic-provided skills.

A skill is a folder of instructions an agent loads on demand, uploaded as files with a `SKILL.md` at its root. Create a skill, add a version, read the versions back and delete the skill:

```bash
A=(-H 'x-api-key: sk-ant-placeholder' -H 'anthropic-version: 2023-06-01')
mkdir -p release-notes && printf -- '---\nname: release-notes\ndescription: Drafts release notes.\n---\nWrite notes.\n' > release-notes/SKILL.md
curl -s "${A[@]}" "$RYSTIC_URL/v1/skills" -F 'display_title=Release notes' -F 'files[]=@release-notes/SKILL.md;filename=release-notes/SKILL.md' | jq -c '{id, display_name, latest_version_id}'
# -> {"id":"skill_01J00000000000000000000001","display_name":"Release notes","latest_version_id":"skillver_01J00000000000000000000001"}
printf -- '---\nname: release-notes\ndescription: Drafts release notes, second draft.\n---\nWrite better notes.\n' > release-notes/SKILL.md
curl -s "${A[@]}" "$RYSTIC_URL/v1/skills/skill_01J00000000000000000000001/versions" -F 'files[]=@release-notes/SKILL.md;filename=release-notes/SKILL.md' | jq -c '{id, name, description}'
# -> {"id":"skillver_01J00000000000000000000002","name":"release-notes","description":"Drafts release notes, second draft."}
curl -s "${A[@]}" "$RYSTIC_URL/v1/skills/skill_01J00000000000000000000001" | jq -c '{latest_version_id}'
# -> {"latest_version_id":"skillver_01J00000000000000000000002"}
curl -s "${A[@]}" "$RYSTIC_URL/v1/skills/skill_01J00000000000000000000001/versions" | jq -c '[.data[].id]'
# -> ["skillver_01J00000000000000000000002","skillver_01J00000000000000000000001"]
curl -s "${A[@]}" "$RYSTIC_URL/v1/skills" | jq -c '[.data[] | select(.source.type == "anthropic") | .display_name]'
# -> ["PDF Report Builder"]
curl -s "${A[@]}" -X DELETE "$RYSTIC_URL/v1/skills/skill_01J00000000000000000000001" | jq -c .
# -> {"id":"skill_01J00000000000000000000001","type":"skill_deleted"}
```

### Creating skills and versions

`POST /v1/skills` takes `files[]` parts under one top-level directory with a `SKILL.md` at its root. The skill's `display_name` comes from a `display_title` form field, as on the API. Without one, it falls back to the `name` in the `SKILL.md` front matter.

The SDKs' `skills.create(display_name=…)` sends a field the API does not read. To set the name, send `display_title`, in Python through `extra_body={"display_title": "…"}`.

`POST /v1/skills/{skill_id}/versions` adds a version and moves `latest_version_id` to it. A version whose `SKILL.md` names a different skill returns 400 `invalid_request_error`.

### Reading skills

Skills and versions are listed, read and deleted, and an unknown skill returns 404 `not_found_error`. The `anthropic_skill_library` scenario holds three skills with six versions between them: Invoice Parser and Brand Style Guide (custom) and PDF Report Builder (from Anthropic), each skill pointing at a latest version that exists.

---

Source: https://www.rystic.ai/docs/simulators/anthropic/features/skills · Markdown: https://www.rystic.ai/docs/simulators/anthropic/features/skills.md