Claude Skills API: Upload, Version, Review, and Roll Back
On this page
Quick answer
The Claude Skills API lets a workspace upload reusable folders of instructions, scripts, templates, and resources, create versions, and attach a chosen skill and version to a Messages API request. API Skills run with the code execution tool in Anthropic’s container.
Treat a custom Skill as workspace-wide executable software, not a prompt snippet. Review every file, pin a tested version in production, separate author and approver roles, and keep a rollback path. API Skills have no network access or runtime package installation, but they can still misuse files, bash, code execution, and the data made available to the container.
Skill identity and sharing
Every Skill needs a SKILL.md file with metadata and instructions. Extra scripts, references, and templates load only when the instructions call for them. That progressive disclosure reduces context use; it does not make bundled content trustworthy.
Custom Skills uploaded through the Claude API are shared across the workspace. All workspace members can access them. That differs from claude.ai custom Skills, which are uploaded per user, and Claude Code Skills, which can live in personal or project directories.
Choose and document the product surface before designing governance. An approval process for a personal Claude Code folder is not sufficient for a workspace-wide API Skill.
A production version lifecycle
1. Build a minimal package
Keep one clear purpose, a narrow description, explicit inputs and outputs, and only the scripts or templates needed. Remove credentials, local paths, generated artifacts, test data, and unreviewed binaries.
2. Review like code
Inspect SKILL.md, every referenced file, commands, path handling, file writes, data flow, error handling, and generated output. Check archives before upload rather than assuming the visible instruction file is the whole package.
3. Upload and create a version
Record the skill ID, version ID, source commit, archive hash, reviewer, test suite, and intended workspace. Creation proves only that the package was accepted by the API.
4. Test with a pinned version
Attach the exact version to representative requests. Test normal work, malformed inputs, missing files, large files, hostile embedded instructions, unexpected output paths, timeouts, and generated-file retrieval. Review artifacts, not only the final chat text.
5. Promote gradually
Start with a bounded cohort and compare the same acceptance cases against the prior version. Do not use latest in a production workflow unless your release system deliberately resolves and records it.
6. Roll back or delete
Rollback means repinning requests to a known version. Deleting a version is destructive and can break callers that reference it. Inventory consumers before deletion and keep a retention rule for source packages, test evidence, and generated files.
Runtime and security boundaries
The Claude API Skills runtime has no network access, no runtime package installation, and only preconfigured dependencies. These constraints should shape the Skill: bring required source data in through reviewed files, use supported libraries, and fail clearly when a dependency is unavailable.
No network access is not a complete security control. A Skill can still read sensitive inputs, write misleading artifacts, consume excessive resources, or invoke available tools incorrectly. Give the container only the files needed for the current request and validate the outputs before distribution.
Anthropic recommends treating Skills like software and auditing all bundled content. Its enterprise content scanning for claude.ai and Cowork uploads does not cover Skills uploaded through the Skills API or Console, so API teams must keep their own review gate.
Skills and Files API handoff
Skills that create Word, PDF, PowerPoint, or spreadsheet artifacts return file IDs inside code-execution results. Download those generated files through the Files API, validate type and content, and assign an owner for delivery and deletion. Input uploads and generated outputs do not have identical download behavior; see the Files lifecycle guide.
Use the GA overview to combine Skills with computer or browser actions, and the readiness checklist before production access.
Official sources
Source check: August 23, 2026. Recheck endpoint headers, runtime dependencies, workspace sharing, audit coverage, and deletion behavior before changing a production Skill.