skein_create
⚠ DEPENDENCIES: use the dependencies array to wire typed edges (blocks / waits-for / related / discovered-from / supersedes / duplicates / parent-child) to existing issues atomically with the create. Do NOT write "depends on X" / "blocks Y" / "requires X" in description, acceptance or notes — prose refs are invisible to the dependency graph, skein_ready gating, the UI Dependencies section and close-time warnings. For a hierarchical child prefer the parentId parameter on this same call; for edges on an EXISTING issue use skein_dep_add. ANSWERS WITH AN ACKNOWLEDGEMENT by default — the id, the applied state and the new version, no issue card and no prose — so the expectedVersion cycle continues without a re-read; pass verbose for the full IssueDetail.
Create a new issue. Two-layer duplicate detection (pg_trgm title similarity + semantic vector rerank) runs natively — do NOT preflight with skein_search or skein_prime to 'check for duplicates'. On a match returns {created:false, duplicates:[...], decisionRequired:true}: decide yourself — retry with force:true if it is distinct, or call again with duplicateOf:"demo-42" (links a duplicates edge). degraded semantics: skein_get_instructions ("Duplicate detection").
kind (REQUIRED for agent callers) sets the issue's source column — see the parameter. The optional sourceContext annotates the trigger further. parentId switches id-generation to hierarchical (parent.N) regardless of project default. id is honoured only when idMode=custom.
Inline dependencies[] (max 50) are created in the SAME SERIALIZABLE tx as the issue insert — any failed edge (cycle, target invisible, target missing, duplicate edge) rolls back the entire create and returns a validation_error / dependency_* code naming the failing index. Cross-project edges are allowed; the caller must already see both projects. The new issue is on the FROM side of each edge.
Assignee default: without assignee, the issue is assigned to YOU (the API key's owner) and accepted, if your personal setting "Assign issues my agent creates to me" is on (the default; switch it in the web UI notification settings). Not for standing tasks, and not under someone else's parent: when the nearest assigned ancestor is another person, or one you cannot see, the issue stays unassigned. Pass unassigned: true when the user asks for an unassigned issue; to drop the assignee later, clear it with skein_update (assignee=""). Being the assignee is not a lock: skein_claim is still needed to start work.
⚠ Field bleed: tool-call wrapper literals (<invoke, <parameter name=, </parameter>) in the prose fields (description / acceptanceCriteria / notes / design) are rejected with validation_error (code: tool_call_syntax_leaked) — a hit means you closed a parameter block with the wrong tag. Closed set + the look-alikes that are NOT rejected: skein_get_instructions ("Text fields — forbidden literals").
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project": "<project>",
"title": "<title>",
"type": "<type>"
},
"name": "skein_create"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Explicit id (custom mode only). Must be "<prefix>-<suffix>" matching the project's id_prefix. | |
| kind | No | Issue origin classification (REQUIRED for agent callers) — sets the stored `source` column: "directed" → `source="agent_directed"`, the human user told the agent to create this issue; "autonomous" → `source="agent_autonomous"`, the agent decided to create it mid-task (side-quest, discovered subtask). The web UI ignores this parameter and forces source=human; MCP callers must specify it. | |
| type | Yes | Issue type. | |
| force | No | Bypass the duplicate gate. Default: false. | |
| notes | No | Free-form notes. | |
| title | Yes | Short imperative title (1..1000 chars). | |
| design | No | Design notes / approach. | |
| idMode | No | Override the project's default id-generation mode. | |
| labels | No | Free-form labels to attach. | |
| project | Yes | Project handle: alias, name, or UUID. | |
| verbose | No | Return the full IssueDetail, prose included. Default false = acknowledgement: `id`, `ok`, `version` plus the post-state stamps that apply (`status`, `assignee`, lock / claim / close stamps) — no issue card and no free text. The version is always there, so the expectedVersion cycle needs no extra read. Details: skein_get_instructions. If the write applied but its card could not be read back, the answer is the acknowledgement plus `cardUnavailable: true` — read the card with skein_show; do not repeat the write. | |
| assignee | No | Assignee handle (username, email, or user UUID — stored verbatim, resolved on read; it resolves only to a person who may work in the project). A user UUID that does not name such a person is refused with assignee_not_allowed. Omitted or blank — your personal "Assign issues my agent creates to me" setting decides (on by default: you become the assignee, accepted), except for standing tasks and issues under someone else's parent. null counts as omitted; a non-string value (number, array, object, boolean) is refused with validation_error and nothing is created. | |
| parentId | No | Full hierarchical id of the parent issue (e.g. "demo-42"). Switches id-generation to hierarchical. | |
| priority | No | Priority 0..4 (0=highest). Default: 3. | |
| standing | No | Create the issue as a standing task instead of the default `open`. STANDING task = perpetual obligation: acted on via spawned children (skein_create parentId=<this>), never claimed or worked in place, excluded from open-work counts / skein_ready / inbox. Standing under standing is rejected with `nested_standing_forbidden`. To promote an existing task instead, use skein_update(status=standing). See skein_get_instructions ("Standing tasks"). Default: false. | |
| unassigned | No | Leave the issue without an assignee even when your personal "Assign issues my agent creates to me" setting is on. Pass it when the user asks for an unassigned issue. Cannot be combined with a non-empty `assignee`. Omitted, null or false — the setting decides. | |
| description | No | Long-form description (markdown). | |
| duplicateOf | No | Full hierarchical id of an existing issue this should be flagged as a duplicate of. Skips the duplicate gate AND auto-creates a `duplicates` dependency edge from the new issue to the supplied one, in the same transaction — if the edge cannot be written, nothing is created. | |
| componentIds | No | Component UUIDs to attach. Must belong to the same project. | |
| dependencies | No | Typed dependency edges created atomically with this issue. Each entry is {toId, type, gate?}; the new issue is on the FROM side of every edge, and direction is canonical per type. Max 50 per call, same type/gate semantics as skein_dep_add — any failed edge rolls back the entire create. For hierarchy prefer the top-level `parentId` (picks the next `parent.N` id); to make an EXISTING issue a child of this new one, create it first, then skein_reparent the child. Type table: skein_get_instructions ("Dependency edge types"). | |
| sourceContext | No | Free-form annotation describing why the agent created this issue (e.g. "while implementing sk-42"). | |
| reviewRequired | No | Whether the issue's author will want to review the result once it is closed. Private bookkeeping of the AUTHOR: it is never returned to anyone else and never shows up in any feed. Omit it and your personal default applies (built-in default: true) — the same default every other creation path uses. Pass false to opt this one issue out. | |
| acceptanceCriteria | No | Acceptance criteria (markdown). |