| name | arcana-upload-api |
| description | Upload a Claude Code skill to the Anthropic Skills API for workspace-wide availability. Analyzes the skill, bundles dependencies, transforms frontmatter, validates, and uploads. Tracks uploads for future updates. Trigger phrases: "upload to API", "publish skill", "sync to API", "upload skill".
|
Arcana Upload API: Upload to Messages API
Upload a Claude Code skill to the Anthropic Skills API.
Path Convention
{PLUGIN_ROOT} = This plugin's root directory (where plugin.json lives)
Prerequisites
ANTHROPIC_API_KEY environment variable must be set- Python 3.8+ with
requests and pyyaml packages
What This Does
- Analyzes the skill to understand what it does
- Identifies all files the skill needs
- Transforms frontmatter (strips CC-only fields)
- Validates for API compatibility
- Creates a ZIP file
- Uploads to Anthropic Skills API
- Tracks the upload for future updates
Workflow
Step 1: Check Prerequisites
Verify API key is set:
if [ -z "$ANTHROPIC_API_KEY" ]; then
echo "ANTHROPIC_API_KEY not set"
fi
If not set, ask user to set it.
Step 2: Check State
Read {PLUGIN_ROOT}/lib/patterns/state-tracking.md for guidance.
Check if this skill has been uploaded before:
python3 "{PLUGIN_ROOT}/lib/tools/state.py" get {skill-name}
If found:
- Inform user: "Skill already uploaded (v2). Will create new version."
- Use stored skill_id for version creation
If not found:
- Inform user: "New skill. Will create."
Step 3: Analyze the Skill
Same as export-zip - read {PLUGIN_ROOT}/lib/patterns/skill-analysis.md.
- Read the SKILL.md
- Explore the skill directory
- Trace dependencies
- Build file manifest
Step 4: Transform Frontmatter
Same as export-zip - read {PLUGIN_ROOT}/lib/patterns/frontmatter-transform.md.
Strip CC-only fields, keep name/description/version.
Step 5: Validate
Same as export-zip - read {PLUGIN_ROOT}/lib/references/validation-rules.md.
Validate name and description.
Step 6: Create ZIP
Same as export-zip:
python3 "{PLUGIN_ROOT}/lib/tools/zip_skill.py" \
--name {skill-name} \
--output /tmp/{skill-name}.zip \
--base-path {temp-directory} \
{files...}
Step 7: Upload to API
Read {PLUGIN_ROOT}/lib/references/api-spec.md for API details.
For new skill:
python3 "{PLUGIN_ROOT}/lib/tools/api.py" upload /tmp/{skill-name}.zip \
--title "{Skill Title}"
For existing skill (new version):
python3 "{PLUGIN_ROOT}/lib/tools/api.py" version {skill_id} /tmp/{skill-name}.zip
Step 8: Update State
Record the upload:
python3 "{PLUGIN_ROOT}/lib/tools/state.py" set {skill-name} \
--skill-id {skill_id} \
--source-path {original-skill-path}
Step 9: Report Result
New skill:
Upload complete!
Skill: my-skill
ID: skill_01AbCdEfGhIjKlMnOpQrStUv
Version: 1
Status: Created
To use in Messages API:
{
"container": {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest"
}
]
}
}
Updated skill:
Upload complete!
Skill: my-skill
ID: skill_01AbCdEfGhIjKlMnOpQrStUv
Version: 3 (updated from v2)
Status: New version created
The latest version is now active for "version": "latest"
Example Session
User: Upload the github-helper skill to the API
Claude:
- Checking ANTHROPIC_API_KEY... ✓ Set
- Checking state... Not found (new skill)
- Reading skill at
/path/to/github-helper/SKILL.md...
- This skill helps with GitHub operations.
- Found dependencies: 2 files
- Transforming frontmatter (stripping: allowed-tools, hooks)...
- Validation passed
- Creating ZIP...
- Uploading to API...
python3 lib/tools/api.py upload /tmp/github-helper.zip --title "GitHub Helper"
{
"id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"title": "GitHub Helper",
"version": 1
}
- Recording state...
Upload complete!
Error Handling
| Error | Resolution |
|---|
| API key not set | Ask user to set ANTHROPIC_API_KEY |
| 401 Unauthorized | Check API key is valid |
| 422 Validation error | Check name/description, report specific issue |
| 429 Rate limited | Wait and retry |
| Network error | Retry with backoff |
Cleanup
After successful upload, optionally delete the temporary ZIP:
rm /tmp/{skill-name}.zip
Related Patterns
{PLUGIN_ROOT}/lib/patterns/skill-analysis.md - How to analyze skills{PLUGIN_ROOT}/lib/patterns/state-tracking.md - How to track uploads{PLUGIN_ROOT}/lib/references/api-spec.md - API specification
