TEteaflask
authed

Edit a skill as a draft

Save an edit to a skill's SKILL.md as a draft revision; it isn't live until published with publish_skill. Read the skill with get_skill just before editing and pass its latest_revision.id as parent_revision_id and latest_revision.content_version as parent_content_version. If anyone changed the skill since that read, nothing is stored and you're told so: read it again, reapply your edit, and save again.

post/api/v1/skills/{skill_id}/revisions

Request

  • Base URL
    https://api.teaflask.com (the document declares no server; this is the origin it was published from)
  • URL
    https://api.teaflask.com/api/v1/skills/{skill_id}/revisions
  • Auth
    none declared

Path parameters

skill_idstring uuid required

The skill's id, as list_skills returns it.

Request body

contentstring required

The whole SKILL.md, shaped like get_skill's latest_revision.content; its frontmatter name must stay the skill's.

parent_revision_idstring uuid required

latest_revision.id from get_skill, read just before editing.

parent_content_versioninteger required

latest_revision.content_version from the same read.

amend_working_draftboolean

Leave false unless re-saving a draft you just saved. When true and latest_revision is your own unpublished draft saved in the last 30 minutes, that draft is updated in place and keeps its id; otherwise a new draft revision is added with a new id.

Response

The editor's open working draft was amended in place

idstring uuid required

The revision's id.

skill_idstring uuid required

The skill it belongs to.

parent_revision_idstring uuid nullable required

The revision this one was edited from; null for the first.

contentstring required

The whole SKILL.md as written: frontmatter, then the instructions.

descriptionstring required

What the skill is for, from the frontmatter; agents read it to decide when to load the skill.

metadataobject required

The frontmatter's metadata map, as written.

licensestring nullable required

The license the frontmatter names; null when none.

instructionsstring required

The instructions an agent follows once it loads the skill: the SKILL.md body after the frontmatter.

content_format'skill/v1' required

Versions of the SKILL.md dialect; evolves additively, never in place. skill/v1 is the agentskills.io shape the skillv1 write gate enforces.

status'draft' | 'published' | 'superseded' required
authored_by_user_idstring uuid required

The member who wrote it.

content_versioninteger required

Changes each time this revision is edited in place; send it back as parent_content_version.

created_atstring date-time required

When the revision was created.

updated_atstring date-time required

When the revision last changed: an edited draft or a status change.

Changes

No recorded changes to this operation across all 1 revision of this API.