arcana-upload-api

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

1. Analyzes the skill to understand what it does
2. Identifies all files the skill needs
3. Transforms frontmatter (strips CC-only fields)
4. Validates for API compatibility
5. Creates a ZIP file
6. Uploads to Anthropic Skills API
7. 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.

1. Read the SKILL.md
2. Explore the skill directory
3. Trace dependencies
4. 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:

1. Checking ANTHROPIC_API_KEY... ✓ Set
2. Checking state... Not found (new skill)
3. Reading skill at /path/to/github-helper/SKILL.md...
4. This skill helps with GitHub operations.
5. Found dependencies: 2 files
6. Transforming frontmatter (stripping: allowed-tools, hooks)...
7. Validation passed
8. Creating ZIP...
9. Uploading to API...

python3 lib/tools/api.py upload /tmp/github-helper.zip --title "GitHub Helper"

{
  "id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
  "title": "GitHub Helper",
  "version": 1
}

10. 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