{"openapi":"3.1.0","info":{"title":"RemoteSkill API","version":"1.0.0","description":"The RemoteSkill product surface: a private, hosted skill library served to every client. Reads address a skill by name, former name, or stable ID; names are not unique, and a name matching more than one skill answers 409 carrying every candidate with its ID. Anything destructive addresses its skill by stable ID alone, because a name is content and only an ID stays put: writing, editing, or deleting a file, and deleting, detaching, renaming, or changing the sharing of a skill. File paths are skill-relative resource identifiers served by the API, not traversable filesystem paths."},"servers":[{"url":"https://api.remoteskill.md"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A RemoteSkill API key (rsk_...) or an OAuth access token issued for this account. An API key carries the account's full access. An OAuth access token is read-only on this API: it proves who the user is, not consent to destructive operations, so writes answer 403. Among permitted writes, what a write may touch is decided by the skill, never the credential: a skill with an update mechanism is read-only for everyone."}},"schemas":{},"parameters":{}},"paths":{"/v1/me":{"get":{"security":[{"bearerAuth":[]}],"summary":"Check the caller's credentials","responses":{"200":{"description":"The credentials are valid for an account","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills":{"get":{"security":[{"bearerAuth":[]}],"summary":"List the account's skill catalog","responses":{"200":{"description":"Every skill in the account, each with its stable ID. A skill carrying a mechanism is read-only here and changes wherever that mechanism points; one without it is editable. Names may repeat, so address a skill by ID whenever it matters.","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"mechanism":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["github"]},"owner":{"type":"string"},"repo":{"type":"string"},"ref":{"type":"string"},"refIsExplicit":{"type":"boolean"},"path":{"type":"string"},"commit":{"type":"string"},"viaInstallation":{"type":"boolean"},"repositoryPrivate":{"type":"boolean"},"url":{"type":"string"}},"required":["type","owner","repo","ref","refIsExplicit","path","commit","viaInstallation","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["shared"]},"sharedBy":{"type":"string"},"sourceSkillId":{"type":"string"}},"required":["type","sharedBy"]}]},"updating":{"type":"boolean"},"refusal":{"type":"object","properties":{"commit":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"},"actual":{"type":"number"},"preview":{"type":"string"}},"required":["commit","rule","message"]},"serving":{"type":"boolean"},"shared":{"type":"boolean"},"shareUrl":{"type":"string"},"fileCount":{"type":"integer","minimum":0},"totalBytes":{"type":"integer","minimum":0},"tokens":{"type":"object","properties":{"skillMd":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","url","updating","serving","shared","fileCount","totalBytes","tokens","createdAt","updatedAt"]}}},"required":["skills"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"security":[{"bearerAuth":[]}],"summary":"Create a hosted skill from SKILL.md content","description":"Creates a skill nothing updates: hosted here, editable, and served everywhere, under the same content rules and account limits as an upload. The name and the description both come from the content's frontmatter, because a name is content: there is no name field to disagree with the file. A name another live skill already answers to is refused with 409 carrying every holder in details.candidates, each with its stable ID, so write into the one you meant by ID or create under another name. A name another creation is still landing answers 409 creation_in_progress: retry after it settles.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"skillMd":{"type":"string","description":"The skill's SKILL.md content, stored verbatim as its entry file. Its frontmatter name is the skill's name."}},"required":["skillMd"]}}}},"responses":{"200":{"description":"The created skill, with the dashboard address it now answers at. formerNameOf warns that the name was another skill's former name, whose alias this creation retired.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"formerNameOf":{"type":"string"}},"required":["id","name","url"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills/{skill}":{"get":{"security":[{"bearerAuth":[]}],"summary":"Read a skill with its file manifest","description":"Pass include=skillMd to receive the skill's SKILL.md alongside the manifest, read in the same transaction. Prefer it over two requests: separate reads of the manifest and of SKILL.md can land either side of a change or of a sharer turning sharing off, and the pair they produce then describes no state the skill was ever in.","parameters":[{"schema":{"type":"string","description":"Skill name, former name, or stable skill ID.","example":"my-skill"},"required":true,"description":"Skill name, former name, or stable skill ID.","name":"skill","in":"path"},{"schema":{"type":"string","enum":["skillMd"],"description":"Ask for SKILL.md alongside the manifest."},"required":false,"description":"Ask for SKILL.md alongside the manifest.","name":"include","in":"query"}],"responses":{"200":{"description":"Skill detail. Files are skill-relative resource identifiers.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"mechanism":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["github"]},"owner":{"type":"string"},"repo":{"type":"string"},"ref":{"type":"string"},"refIsExplicit":{"type":"boolean"},"path":{"type":"string"},"commit":{"type":"string"},"viaInstallation":{"type":"boolean"},"repositoryPrivate":{"type":"boolean"},"url":{"type":"string"}},"required":["type","owner","repo","ref","refIsExplicit","path","commit","viaInstallation","url"]},{"type":"object","properties":{"type":{"type":"string","enum":["shared"]},"sharedBy":{"type":"string"},"sourceSkillId":{"type":"string"}},"required":["type","sharedBy"]}]},"updating":{"type":"boolean"},"refusal":{"type":"object","properties":{"commit":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"},"actual":{"type":"number"},"preview":{"type":"string"}},"required":["commit","rule","message"]},"serving":{"type":"boolean"},"shared":{"type":"boolean"},"shareUrl":{"type":"string"},"fileCount":{"type":"integer","minimum":0},"totalBytes":{"type":"integer","minimum":0},"tokens":{"type":"object","properties":{"skillMd":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"kind":{"type":"string","enum":["text","binary"]},"size":{"type":"integer","minimum":0},"sha256":{"type":"string"},"flagged":{"type":"boolean"},"tokens":{"type":"integer","minimum":0}},"required":["path","kind","size","sha256","flagged"]}},"aliases":{"type":"array","items":{"type":"string"}},"skillMd":{"type":"string"}},"required":["id","name","description","url","updating","serving","shared","fileCount","totalBytes","tokens","createdAt","updatedAt","files","aliases"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"security":[{"bearerAuth":[]}],"summary":"Delete a skill","description":"Removes the skill from the catalog, frees the names it answered to, and destroys its files. Anyone following it stops receiving it, the same as turning sharing off. This cannot be undone, which is why it is addressed by stable ID alone.","parameters":[{"schema":{"type":"string","description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","example":"7fk29dbq1m4x"},"required":true,"description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","name":"skill","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills/{skill}/rename":{"post":{"security":[{"bearerAuth":[]}],"summary":"Rename a skill","description":"Addressed by stable ID: a rename rewrites the SKILL.md of whichever skill it resolves, and a hosted skill has no history to put back. Only a skill nothing updates can be renamed: one mirroring a repository or following another person takes its name from that source, and renaming it here answers 409 source_read_only. The former name keeps resolving until another skill legitimately claims it, and the response warns when the new name was another skill's former name.","parameters":[{"schema":{"type":"string","description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","example":"7fk29dbq1m4x"},"required":true,"description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","name":"skill","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"The rename result","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"formerNameOf":{"type":"string"},"duplicateOf":{"type":"string"}},"required":["name"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills/{skill}/detach":{"post":{"security":[{"bearerAuth":[]}],"summary":"Detach a skill from whatever updates it","description":"Keeps every file, removes the update mechanism, and stops refreshing. The skill becomes an ordinary skill of its own and can be edited. One way: there is no reattach. For a skill that follows someone else's, this is also the only way to keep it: it copies what the skill is serving right now, so it must be done while they are still sharing. Addressed by stable ID alone, because there is no reattach.","parameters":[{"schema":{"type":"string","description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","example":"7fk29dbq1m4x"},"required":true,"description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","name":"skill","in":"path"}],"responses":{"200":{"description":"Detached","content":{"application/json":{"schema":{"type":"object","properties":{"detached":{"type":"boolean","enum":[true]}},"required":["detached"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills/{skill}/export":{"get":{"security":[{"bearerAuth":[]}],"summary":"Export a skill as a ZIP","description":"Responds with the ZIP itself. The archive's single root folder is the skill's own name, which is what the Agent Skills specification requires of a skill directory, and the file name in Content-Disposition is that name plus .zip: take the download name from the response rather than from whatever you looked the skill up by, and expect two same-named skills to download under one name. A name that is a Windows device name (con, prn, aux, nul, com0-com9, lpt0-lpt9) is the one exception and carries the skill's ID after it, because such a name cannot be a folder or a file. Nothing here ever returns an object-storage URL.","parameters":[{"schema":{"type":"string","description":"Skill name, former name, or stable skill ID.","example":"my-skill"},"required":true,"description":"Skill name, former name, or stable skill ID.","name":"skill","in":"path"}],"responses":{"200":{"description":"The ZIP","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/add":{"post":{"security":[{"bearerAuth":[]}],"summary":"Add one skill from a link","description":"Takes one link and adds the one skill it names. Two links work: a GitHub link to a skill's SKILL.md on a branch, in either the github.com/{owner}/{repo}/blob/{branch}/{path}/SKILL.md or raw.githubusercontent.com spelling, or the /tree/ link to that same directory; and a RemoteSkill share link. A public repository needs nothing; a private one needs the RemoteSkill GitHub App installed on the account that owns it, and the refusal says so. One link per call: each add has its own outcome, its own limit check, and its own failure, so five links are five calls. If a skill of the account already updates from that exact repository directory, it is refreshed in place and outcome is updated: its served content is replaced with the repository's current state, and a file gone upstream leaves the library with it, because a mirror keeps no history. A name collision never replaces anything: a different skill sharing the name is kept beside the new one, because names are not unique here and the ID tells them apart.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"string","example":"https://github.com/owner/repo/blob/main/path/to/skill/SKILL.md"},"mode":{"type":"string","enum":["follow","copy"],"description":"Share links only. follow keeps the skill updating from the person who shared it and stops working if they stop sharing; copy takes a detached copy that is yours to edit and never updates again. Defaults to follow, the same default the dashboard offers. Refused for a GitHub link."}},"required":["link"]}}}},"responses":{"200":{"description":"The skill that was added, with the address it answers at","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"outcome":{"type":"string","enum":["added","updated"]},"mechanism":{"type":"string","enum":["github","shared"]},"formerNameOf":{"type":"string"}},"required":["id","name","url","outcome"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills/{skill}/share":{"post":{"security":[{"bearerAuth":[]}],"summary":"Turn sharing on or off for a skill","description":"Sharing is a switch, not a visibility level: there are no levels, permissions, or membership. While it is on, anyone holding the link can read the skill and add it, and anyone who added it following you receives your changes. Turning it off is one transaction and takes effect when this call returns: the link is dead, nobody can add the skill, and everyone following it stops receiving it. They keep nothing, because following stores nothing on their side, and a recipient who wants to keep a shared skill detaches it while the share is live. Turning sharing back on resumes everyone who is still following. Addressed by stable ID alone: turning it off ends every follower's access the instant this returns, and turning it on hands out a live link to whatever the skill holds.","parameters":[{"schema":{"type":"string","description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","example":"7fk29dbq1m4x"},"required":true,"description":"Stable skill ID, from GET /v1/skills. A name is refused here: names are not unique and a former name can move to another skill, so an address for something destructive is the one thing that never moves.","name":"skill","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"shared":{"type":"boolean"}},"required":["shared"]}}}},"responses":{"200":{"description":"The skill's sharing state, its ID, and, while sharing is on, the public address anyone can open. The badge lives one segment under that address, at /badge.svg.","content":{"application/json":{"schema":{"type":"object","properties":{"shared":{"type":"boolean"},"id":{"type":"string"},"shareUrl":{"type":"string"}},"required":["shared","id"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/share/{id}/add":{"post":{"security":[{"bearerAuth":[]}],"summary":"Add a skill someone shared","description":"follow keeps the skill updating from the person who shared it, stores nothing of its own, and stays read-only here. If they stop sharing it, it stops working, and detaching it before then is what turns it into a copy of your own. copy takes that detached copy straight away: yours to edit, and it never changes on its own again. Either way it counts against the account's own limit and passes the same content rules as any import.","parameters":[{"schema":{"type":"string","description":"The skill ID a share link carries."},"required":true,"description":"The skill ID a share link carries.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["follow","copy"],"default":"follow"}}}}}},"responses":{"200":{"description":"The skill that was added","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/skills/{skill}/files/{filePath}":{"get":{"summary":"Read a bundled file","description":"Responds with the file's bytes, whatever it is: text inline from the database, binary and oversized content streamed through this API from object storage. Nothing here ever returns an object-storage URL, so a read is authorized on every request rather than once per link.","parameters":[{"name":"skill","in":"path","required":true,"schema":{"type":"string"},"description":"Skill name, former name, or stable skill ID."},{"name":"filePath","in":"path","required":true,"schema":{"type":"string"},"description":"Skill-relative resource identifier from the skill's manifest, e.g. references/guide.md. May contain slashes."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The file content. The response content type follows the file, so a client must decode by the header rather than by this list.","content":{"text/markdown":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/yaml":{"schema":{"type":"string"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing or invalid file path","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"No such skill or file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill has an update mechanism and is read-only, the name matched more than one skill, or an exact edit matched other than once (edit_match_failed) or addressed a file too large to edit that way (edit_requires_inline)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}},"put":{"summary":"Write a text file","description":"Editable skills only, addressed by stable ID. The text supplied becomes the file's whole content, with no version behind it, and creates the file when the path is new. A skill with an update mechanism, a GitHub repository or another person's shared skill, is read-only here and answers 409 source_read_only: detach it in RemoteSkill to edit it: detaching keeps its files, stops the updates, and makes it editable.","parameters":[{"name":"skill","in":"path","required":true,"schema":{"type":"string"},"description":"Stable skill ID, from GET /v1/skills. A write never resolves a name: names are not unique and a former name can move to another skill, so anything but an ID answers 400 validation_failed and changes nothing.","example":"Sk1LLaaaaaa9"},{"name":"filePath","in":"path","required":true,"schema":{"type":"string"},"description":"Skill-relative resource identifier from the skill's manifest, e.g. references/guide.md. May contain slashes."}],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}}}},"responses":{"200":{"description":"Written. Returns the updated manifest entry, whether the path was new, and, for a SKILL.md write, the skill's resulting identity","content":{"application/json":{"schema":{"type":"object","properties":{"written":{"type":"boolean","enum":[true]},"created":{"type":"boolean"},"entry":{"type":"object","properties":{"path":{"type":"string"},"kind":{"type":"string","enum":["text","binary"]},"size":{"type":"integer"},"sha256":{"type":"string"},"flagged":{"type":"boolean"},"tokens":{"type":"integer","description":"The file's size in tokens, present for a text file held inline once its landing counted it."}},"required":["path","kind","size","sha256","flagged"]},"identity":{"type":"object","description":"The skill's identity after this landing, present exactly when the written path was SKILL.md: its frontmatter carries the name and description, so this write may have renamed the skill.","properties":{"name":{"type":"string"},"description":{"type":"string"},"formerNameOf":{"type":"string","description":"Present when the new name retired another skill's former name."},"duplicateOf":{"type":"string","description":"Present when another live skill already answers to the new name."}},"required":["name","description"]}},"required":["written","created","entry"]}}}},"400":{"description":"The skill segment is not a stable ID, or the path or content is invalid","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"No such skill","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill has an update mechanism and is read-only, the name matched more than one skill, or an exact edit matched other than once (edit_match_failed) or addressed a file too large to edit that way (edit_requires_inline)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}},"patch":{"summary":"Replace one exact fragment of a text file","description":"Editable skills only, addressed by stable ID. oldString is matched literally against the file's current content and must appear exactly once: no match, or more than one, answers 409 edit_match_failed with the count in details and changes nothing. Counting and landing are one backend transaction, which is why this works on files held as inline text: a file over 900,000 bytes, or an edit whose result would be, answers 409 edit_requires_inline and is written whole with PUT instead, which carries an ordinary text file up to 5 MiB. SKILL.md is the exception: PUT holds it to the same 900,000 bytes, because it is answered in one transaction with the file manifest, so there is no larger door for that one file. Everything PUT validates on the file is validated on the result, including SKILL.md's frontmatter and the rename it may carry. A skill with an update mechanism, a GitHub repository or another person's shared skill, is read-only here and answers 409 source_read_only: detach it in RemoteSkill to edit it: detaching keeps its files, stops the updates, and makes it editable.","parameters":[{"name":"skill","in":"path","required":true,"schema":{"type":"string"},"description":"Stable skill ID, from GET /v1/skills. A write never resolves a name: names are not unique and a former name can move to another skill, so anything but an ID answers 400 validation_failed and changes nothing.","example":"Sk1LLaaaaaa9"},{"name":"filePath","in":"path","required":true,"schema":{"type":"string"},"description":"Skill-relative resource identifier from the skill's manifest, e.g. references/guide.md. May contain slashes."}],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"oldString":{"type":"string"},"newString":{"type":"string"}},"required":["oldString","newString"]}}}},"responses":{"200":{"description":"Edited. Returns the updated manifest entry, and, for a SKILL.md edit, the skill's resulting identity","content":{"application/json":{"schema":{"type":"object","properties":{"edited":{"type":"boolean","enum":[true]},"entry":{"type":"object","properties":{"path":{"type":"string"},"kind":{"type":"string","enum":["text","binary"]},"size":{"type":"integer"},"sha256":{"type":"string"},"flagged":{"type":"boolean"},"tokens":{"type":"integer","description":"The file's size in tokens, present for a text file held inline once its landing counted it."}},"required":["path","kind","size","sha256","flagged"]},"identity":{"type":"object","description":"The skill's identity after this landing, present exactly when the written path was SKILL.md: its frontmatter carries the name and description, so this write may have renamed the skill.","properties":{"name":{"type":"string"},"description":{"type":"string"},"formerNameOf":{"type":"string","description":"Present when the new name retired another skill's former name."},"duplicateOf":{"type":"string","description":"Present when another live skill already answers to the new name."}},"required":["name","description"]}},"required":["edited","entry"]}}}},"400":{"description":"The skill segment is not a stable ID, or the path, an empty oldString, or an oversized fragment is invalid","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"No such skill or file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill has an update mechanism and is read-only, the name matched more than one skill, or an exact edit matched other than once (edit_match_failed) or addressed a file too large to edit that way (edit_requires_inline)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}},"delete":{"summary":"Delete a file","description":"Editable skills only, addressed by stable ID. Removes the file with no history to put it back. SKILL.md cannot be deleted. A skill with an update mechanism, a GitHub repository or another person's shared skill, is read-only here and answers 409 source_read_only: detach it in RemoteSkill to edit it: detaching keeps its files, stops the updates, and makes it editable.","parameters":[{"name":"skill","in":"path","required":true,"schema":{"type":"string"},"description":"Stable skill ID, from GET /v1/skills. A write never resolves a name: names are not unique and a former name can move to another skill, so anything but an ID answers 400 validation_failed and changes nothing.","example":"Sk1LLaaaaaa9"},{"name":"filePath","in":"path","required":true,"schema":{"type":"string"},"description":"Skill-relative resource identifier from the skill's manifest, e.g. references/guide.md. May contain slashes."}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"]}}}},"400":{"description":"The skill segment is not a stable ID, or SKILL.md was addressed, which cannot be deleted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"No such skill or file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill has an update mechanism and is read-only, the name matched more than one skill, or an exact edit matched other than once (edit_match_failed) or addressed a file too large to edit that way (edit_requires_inline)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/upload":{"post":{"security":[{"bearerAuth":[]}],"summary":"Start a file upload import","description":"Returns a short-lived direct upload URL. PUT the file bytes to it, then call complete. The upload is either an archive holding a skill directory with SKILL.md at its top level (a .zip, or a .skill, which is the same container under another name), or a single Markdown file that is the whole skill. The format is read from the bytes, not from the name, and the name is not sent at all: a skill's name comes from its SKILL.md frontmatter. Uploads are limited to 9 MiB, 20 MiB extracted, 900 files, 5 MiB per file, and SKILL.md itself to 900,000 bytes, which is the real ceiling on a single Markdown upload because that file becomes the skill's SKILL.md. sizeBytes is required and is signed into the upload URL, so the storage capability itself is bounded: the store rejects any differently sized body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sizeBytes":{"type":"integer","exclusiveMinimum":0,"description":"Exact file size in bytes, signed into the upload URL so the store rejects any differently sized body."}},"required":["sizeBytes"]}}}},"responses":{"200":{"description":"The import and its upload URL","content":{"application/json":{"schema":{"type":"object","properties":{"importId":{"type":"string"},"uploadUrl":{"type":"string"}},"required":["importId","uploadUrl"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/{importId}/complete":{"post":{"security":[{"bearerAuth":[]}],"summary":"Process an uploaded file import","description":"Reads the staged bytes and imports them: an archive opens into a skill directory, and anything else is taken as the skill's SKILL.md.","parameters":[{"schema":{"type":"string"},"required":true,"name":"importId","in":"path"}],"responses":{"200":{"description":"Processing outcome","content":{"application/json":{"schema":{"type":"object","properties":{"importId":{"type":"string"},"status":{"type":"string"}},"required":["importId","status"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/github/discover":{"post":{"security":[{"bearerAuth":[]}],"summary":"Discover the skills a GitHub reference contains","description":"Read-only and idempotent: lists every directory under the reference that contains a SKILL.md, with each candidate's name and description. Nothing is imported and nothing is stored. Import a selection with the batch endpoint.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string","example":"https://github.com/owner/repo/tree/main/skills"},"ref":{"type":"string"}},"required":["repository"]}}}},"responses":{"200":{"description":"The skill candidates the reference contains","content":{"application/json":{"schema":{"type":"object","properties":{"owner":{"type":"string"},"repo":{"type":"string"},"ref":{"type":"string"},"path":{"type":"string"},"commit":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"fileCount":{"type":"integer","minimum":0},"totalBytes":{"type":"integer","minimum":0},"entryCount":{"type":"integer","minimum":0},"skillMdBytes":{"type":"integer","minimum":0},"blocked":{"type":"string","enum":["metadata_invalid","skill_md_too_large","too_many_files","skill_too_large"]},"existing":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"sameSource":{"type":"boolean"}},"required":["skillId","name","sameSource"]}},"required":["path","name","description","fileCount","totalBytes","entryCount"]}},"truncated":{"type":"boolean"}},"required":["owner","repo","ref","path","commit","candidates","truncated"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/github/batch":{"post":{"security":[{"bearerAuth":[]}],"summary":"Import several skills from one GitHub reference","description":"Runs one ordinary import per selected candidate path from a discover result, out of the exact commit that discover answered with. Send that commit back: if the repository has moved since, the import answers 409 source_changed rather than landing bytes nobody reviewed, and a fresh discover gives the current list. Members succeed and fail independently, and a member whose SKILL.md cannot pass validation is reported as failed without consuming the account's limit.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string"},"ref":{"type":"string"},"commit":{"type":"string","description":"The commit the discover result carried. The import lands this exact tree or refuses."},"paths":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":25,"description":"Candidate directory paths from a discover result."}},"required":["repository","commit","paths"]}}}},"responses":{"200":{"description":"The batch and its member imports","content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string"},"imports":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"importId":{"type":"string"},"status":{"type":"string"}},"required":["path","importId","status"]}}},"required":["batchId","imports"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/batches/{batchId}":{"get":{"security":[{"bearerAuth":[]}],"summary":"Read a batch import's members","parameters":[{"schema":{"type":"string"},"required":true,"name":"batchId","in":"path"}],"responses":{"200":{"description":"Every member import in the batch, in start order","content":{"application/json":{"schema":{"type":"object","properties":{"batchId":{"type":"string"},"imports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["awaiting_upload","processing","collision","failed","complete"]},"kind":{"type":"string","enum":["upload","github"]},"skillId":{"type":"string"},"skillName":{"type":"string"},"outcome":{"type":"string","enum":["added","updated"]},"collision":{"type":"object","properties":{"existingSkillId":{"type":"string"},"existingName":{"type":"string"}},"required":["existingSkillId","existingName"]},"report":{"type":"object","properties":{"kept":{"type":"integer","minimum":0},"flagged":{"type":"array","items":{"type":"string"}},"dropped":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}}},"required":["kept","flagged","dropped","rejected"]},"formerNameOf":{"type":"string"},"error":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"path":{"type":"string"}},"required":["id","status","kind","createdAt","path"]}}},"required":["batchId","imports"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/github":{"post":{"security":[{"bearerAuth":[]}],"summary":"Import a skill from a GitHub repository","description":"Accepts a repository URL or owner/repo[/path] reference. Public repositories import directly. Private repositories require the RemoteSkill GitHub App installed on the account. For a reference that holds more than one skill, call the discover endpoint first and import a selection with the batch endpoint. If this import follows a discover, send that discover's commit: the import then lands that exact tree or answers 409 source_changed, the same promise the batch endpoint makes. Either way the import pins one commit for its whole life, so resolving a collision later lands the tree that collided rather than whatever the branch holds by then.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string","example":"https://github.com/owner/repo/tree/main/skills/my-skill"},"ref":{"type":"string"},"commit":{"type":"string","description":"The commit a discover result carried. Sent, the import lands this exact tree or refuses; omitted, the import pins whatever commit it first resolves."}},"required":["repository"]}}}},"responses":{"200":{"description":"Import outcome","content":{"application/json":{"schema":{"type":"object","properties":{"importId":{"type":"string"},"status":{"type":"string"}},"required":["importId","status"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/{importId}":{"get":{"security":[{"bearerAuth":[]}],"summary":"Read an import's status and report","parameters":[{"schema":{"type":"string"},"required":true,"name":"importId","in":"path"}],"responses":{"200":{"description":"Import status, including the kept/flagged/dropped/rejected report and any name collision","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["awaiting_upload","processing","collision","failed","complete"]},"kind":{"type":"string","enum":["upload","github"]},"skillId":{"type":"string"},"skillName":{"type":"string"},"outcome":{"type":"string","enum":["added","updated"]},"collision":{"type":"object","properties":{"existingSkillId":{"type":"string"},"existingName":{"type":"string"}},"required":["existingSkillId","existingName"]},"report":{"type":"object","properties":{"kept":{"type":"integer","minimum":0},"flagged":{"type":"array","items":{"type":"string"}},"dropped":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}},"rejected":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"]}}},"required":["kept","flagged","dropped","rejected"]},"formerNameOf":{"type":"string"},"error":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","kind","createdAt"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}},"/v1/imports/{importId}/resolve":{"post":{"security":[{"bearerAuth":[]}],"summary":"Resolve an import collision","description":"update refreshes the existing skill in place (same source). add imports it beside the one you have, which is legal because names are not unique and the ID tells them apart. replace deletes the existing skill and imports fresh, so it requires targetSkillId, the stable ID of the skill to destroy: the name that collided is not an address, because it can be worn by two skills and can move to another one while the decision sits unanswered. targetSkillId is the existingSkillId the collision reported, and a replace without one, or with anything that is not a stable ID, answers 400 validation_failed.","parameters":[{"schema":{"type":"string"},"required":true,"name":"importId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["update","add","replace"]},"targetSkillId":{"type":"string","description":"Which existing skill a replace destroys, by stable ID, from the collision's existingSkillId. Required for replace, ignored otherwise. A name here is refused rather than resolved."}},"required":["action"]}}}},"responses":{"200":{"description":"Resolution outcome","content":{"application/json":{"schema":{"type":"object","properties":{"importId":{"type":"string"},"status":{"type":"string"}},"required":["importId","status"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Forbidden: the credential lacks a required scope or does not grant this operation","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Conflict: the skill is read-only, an import collided, a creation of the name is still in progress (retry after it settles), or the name matched more than one skill (details.candidates carries each one with its ID)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"413":{"description":"Content exceeds a size limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}},"500":{"description":"Unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","validation_failed","name_invalid","frontmatter_invalid","source_changed","former_name","ambiguous_name","skill_limit_reached","archive_too_large","skill_too_large","file_too_large","too_many_files","archive_invalid","unsafe_archive_entry","missing_skill_md","no_skills_found","binary_rejected","secret_detected","import_collision","creation_in_progress","import_failed","edit_match_failed","edit_requires_inline","source_unavailable","source_read_only","not_attached","not_shared","mechanism_cycle","rate_limited","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"]}},"required":["error"]}}}}}}}},"webhooks":{}}