---
title: "Open a skill draft"
method: POST
path: "/v1/skill-drafts"
tags: ["skill-drafts"]
---

# Open a skill draft

`POST /v1/skill-drafts`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/skill-drafts`
- Auth: HTTP bearer

Start editing a skill without creating a version. Send `skill_id` to edit an EXISTING skill — its active version's manifest and files are copied in and the version number is patch-bumped — or omit it to start a new one, optionally with a starting `manifest` (for example a candidate returned by the GitHub autodetect route). Nothing here is installed, compiled into runtime rows, or visible to anyone else: a draft belongs to the person who opened it until they publish it.

## Headers

- `X-Tenant-Id` string, nullable

## Request body

- CreateDraftRequest: Open a draft: empty, from a manifest, or seeded from an existing skill.
  - `skill_id` string, uuid, nullable: Edit an EXISTING skill: its active version's manifest and files are copied in and the version number is patch-bumped. Omit to start a new skill.
  - `manifest` object, nullable: A starting manifest (for example a GitHub candidate). Ignored when skill_id is set.
  - `skill_md` string, nullable: The starting SKILL.md, stored as an editable draft file. The GitHub autodetect route returns one alongside each candidate's manifest; without this the import would arrive with its prose silently dropped. Ignored when skill_id is set (an existing skill's files are copied instead).
  - `title` string: A working name for the draft.
  - `source_kind` 'manual' | 'github': Which door this draft came through — 'manual' (typed) or 'github' (a candidate picked from /authored-skills/from-github). Stated rather than guessed from the other fields, and carried onto the published version. 'zip' is not accepted here: it belongs to /skill-drafts/upload, which is the only route that actually read an archive.
  - `source_ref` string, nullable: Where this came from — a repo URL or a filename. Inert metadata.

## Response `201`

Successful Response

- SkillDraftDetail: One draft in full, returned to its author alone: the manifest plus the file list.
  - `id` string, uuid, required
  - `skill_id` string, uuid, nullable, required
  - `author_user_id` string, uuid, required
  - `title` string, required
  - `archetype_code` string, required
  - `source_kind` string, required
  - `published_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `file_count` integer
  - `slug` string, required
  - `validated_at` string, date-time, nullable, required
  - `validation_errors` string[]
  - `base_version_stale` boolean
  - `manifest` object
  - `base_version_id` string, uuid, nullable
  - `published_version_id` string, uuid, nullable
  - `files` DraftFileSummary[]
    - `path` string, required
    - `kind` string, required
    - `size_bytes` integer, required
    - `sha256` string, required
  - `source_ref` string, nullable

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED)
- `409`: Conflict
- `422`: Validation error

---

[API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)