# Update Skill

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Skill"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v2/skills/{skill_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update Skill

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"path","name":"skill_id","required":true,"schema":{"title":"Skill Id","type":"string"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"properties":{"files":{"description":"The files that make up the skill.","items":{"description":"A single file within a skill folder.\n\n``content_base64`` is base64 so binary assets (images, PDFs) round-trip losslessly.\n``sha`` is the GitHub blob sha; populated on reads, ignored on writes.","properties":{"content_base64":{"description":"Base64-encoded file content. Base64 keeps binary assets (images, PDFs) lossless on read and write.","title":"File content (base64)","type":"string"},"path":{"description":"Path relative to the skill folder, e.g. 'SKILL.md' or 'reference/forms.md'.","title":"File path","type":"string"},"sha":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Git blob sha of the file. Returned on reads; ignored on writes.","title":"File SHA"}},"required":["path","content_base64"],"title":"SkillFile","type":"object"},"title":"Files","type":"array"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional commit message for this change. If omitted, a message is auto-generated per file.","title":"Commit message"},"source":{"anyOf":[{"description":"Provenance of a skill, for the catalog to badge (e.g. \"Built by deepset\").","enum":["DEEPSET","ORG","WORKSPACE"],"title":"SkillSource","type":"string"},{"type":"null"}],"description":"Where the skill comes from: 'DEEPSET' (built by deepset, from our shared repo), 'ORG' (the organization's own repo), or 'WORKSPACE' (workspace-scoped).","title":"Source"},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the specific repo to write to (from the catalog entry's 'source_id'). Required when the organization has more than one writable repo; disambiguates which one the write lands in. When omitted, writes target the organization's single writable repo.","title":"Source Id"}},"required":["files"],"title":"UpdateSkillRequest","type":"object"}}},"required":true}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"content":{"application/json":{"schema":{"description":"Skill detail returned on get/create/update: metadata + a download URL for the zip archive.","properties":{"archive_url":{"description":"Time-limited URL to download the skill's contents as a zip archive (content-addressed by tree sha).","title":"Archive URL","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Short description of the skill from the manifest, shown in the catalog.","title":"Description"},"editable":{"description":"Whether the organization may modify this skill. False for the shared deepset repo (read-only for orgs); the UI should not offer edit/upload/delete when False.","title":"Editable","type":"boolean"},"id":{"description":"Skill id / folder name in kebab-case (e.g. 'web-research').","title":"Skill ID","type":"string"},"name":{"description":"Human-readable skill name from the manifest; falls back to the id if unset.","title":"Name","type":"string"},"path":{"description":"Path of the skill folder within the repository.","title":"Path","type":"string"},"security":{"anyOf":[{"description":"Automated security-scan verdict for a skill version.","properties":{"files":{"description":"The files behind this verdict, worst severity first — a summary of 'issues' for badging and filtering. Empty when the scanner located no files, and for versions scanned before findings were recorded.","items":{"description":"One file the security scan flagged.","properties":{"path":{"description":"Path of the flagged file, relative to the skill folder.","title":"Path","type":"string"},"severity":{"description":"Worst severity found in this file: LOW | MEDIUM | HIGH | CRITICAL.","title":"Severity","type":"string"}},"required":["path","severity"],"title":"SkillScanFile","type":"object"},"title":"Files","type":"array"},"issues":{"description":"The scanner's individual findings, passed through as reported: typically a rule id, severity, location, the matched snippet, and an explanation. This is the scanner's own schema rather than ours, so treat the keys as advisory and render defensively — it can change when the scanner is upgraded. Empty for versions scanned before findings were recorded.","items":{"additionalProperties":true,"type":"object"},"title":"Issues","type":"array"},"recommendation":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. SAFE | CAUTION | DO_NOT_INSTALL.","title":"Recommendation"},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Numeric risk score (0-100).","title":"Score"},"severity":{"description":"Overall severity: LOW | MEDIUM | HIGH | CRITICAL.","title":"Severity","type":"string"}},"required":["severity"],"title":"SkillScanSummary","type":"object"},{"type":"null"}],"description":"Automated security-scan verdict for this version (severity, score, recommendation). Present on create/update responses; null when scanning is disabled or unavailable.","title":"Security scan"},"security_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Risk score (0-100, higher is riskier) from the security scan of this skill's current version. Recorded on every create/update, so it always describes the version identified by 'sha'. Null when the version has never been scanned — scanning is disabled, was unavailable at write time, or the skill was changed outside the platform (e.g. pushed straight to a connected repository).","title":"Security score"},"sha":{"description":"Git tree sha of the skill folder (identifies the current version).","title":"SHA","type":"string"},"source":{"description":"Provenance of a skill, for the catalog to badge (e.g. \"Built by deepset\").","enum":["DEEPSET","ORG","WORKSPACE"],"title":"SkillSource","type":"string"},"source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the specific connected repo this skill lives in. None for the shared deepset repo. Carried on the durable skill reference so a run resolves the exact repo.","title":"Source Id"},"workspace":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Workspace id this skill is scoped to, when source is WORKSPACE. None for org-wide and deepset skills.","title":"Workspace"}},"required":["id","name","source","editable","path","sha","archive_url"],"title":"SkillDetail","type":"object"}}},"description":"Returns the updated skill's metadata and archive URL."},"400":{"description":"The skill failed validation. {error_message}"},"403":{"description":"The shared deepset skills repository is read-only. Connect your organization's own repository to create, update, or delete skills."},"404":{"description":"The requested skill was not found. The requested skill repository was not found for this organization. It may have been disconnected — reload the skill catalog and retry."},"409":{"description":"The skill was changed concurrently. Re-read the skill and retry."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"}}}
>
  
</StatusCodes>