AI Context Page

# SkillzDrive MCP Integration Context
# Paste this into your AI model's system prompt or context window.
# Base URL: https://www.skillzdrive.com/api/mcp
# Auth: Authorization: Bearer sk_live_YOUR_KEY
# Protocol: MCP (Model Context Protocol) — any compliant client works.

## Available Tools (20 total, 8 categories)

### Discovery (2)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_searchSkills | query | limit, collectionName | Search skills by keyword. Recommended starting point. |
| skills_listSkills | — | query, tags, collectionName | List all accessible skills. |

### Documentation (3)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_docTOC | skillSlug | — | Get documentation table of contents. |
| skills_docSection | skillSlug, sectionSlug | — | Read a specific documentation section. |
| skills_getResourceInfo | skillSlug, filePath | — | Get file metadata (sections, token count, size). |

### Execution (3)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_listScripts | skillSlug | — | List executable scripts. MUST call before runScript. |
| skills_runScript | skillSlug, scriptName | args, stdin, reuseSession, sessionId | Execute script in sandbox. |
| skills_getScript | skillSlug, scriptName | — | Get script source/download URL for local execution. |

### Session Management (3)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_readFile | sessionId, filePath | startLine, limit | Read file from active sandbox. |
| skills_listOutputFiles | sessionId | directory | List files in sandbox directory. |
| skills_closeSession | sessionId | — | Close sandbox session and free resources. |

### Collections (4)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_createCollection | name | skillSlugs | Create a named collection (API key with skill whitelist). |
| skills_updateCollection | collectionName, newName | — | Rename a collection. |
| skills_addToCollection | collectionName, skillSlug | — | Add one skill to a collection. |
| skills_removeFromCollection | collectionName, skillSlug | — | Remove one skill from a collection. |

### Drive Management (2)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_removeFromDrive | skillSlug | — | Remove a skill from your drive entirely. |
| skills_toggleDriveSkill | skillSlug | — | Toggle a skill on/off (keeps it in drive). |

### Marketplace (2)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_discoverSkills | keywords | offset | Search marketplace + GitHub catalog. Returns batches of 10. |
| skills_importToDrive | skillSlug | — | Import a marketplace or GitHub skill to your drive. Charges credits. |

### Export (1)
| Tool | Required Args | Optional Args | Description |
|------|--------------|---------------|-------------|
| skills_downloadSkills | scope | collectionName, skillSlug | Download skills as ZIP. Scopes: drive, collection, skill. |

## Skill Discovery

The skill catalog is dynamic — new skills are added regularly. Never hardcode skill lists.
- Use searchSkills(query) to find skills for a specific task (e.g. "pdf", "image", "spreadsheet")
- Use listSkills() to browse all available skills
- Skills come from 3 sources: your drive, team drives, and skills shared with you

## Workflow: Script-Based Skills (hasScripts: true)

Follow this exact sequence:
1. searchSkills(query) or listSkills() → find the right skill slug
2. listScripts(skillSlug) → get exact script names (NEVER guess)
3. runScript(skillSlug, scriptName, reuseSession: true) → get sessionId
4. readFile(sessionId, "/tmp/last_run.out") → get script output
5. closeSession(sessionId) → free resources

## Workflow: Local-Execution Skills

1. searchSkills(query) or listSkills() → find the skill slug
2. listScripts(skillSlug) → get exact script names (NEVER guess)
3. getScript(skillSlug, scriptName) → get downloadUrl (+ inline content if available)
4. Download + run locally if your environment supports local code execution
Note: Local execution is FREE (no credits charged).

## Workflow: Template-Based Skills (hasScripts: false)

1. docTOC(skillSlug) → get section slugs
2. docSection(skillSlug, sectionSlug) → read relevant content
3. Generate output directly using the documentation

## Workflow: Upload a Skill

1. searchSkills("upload-to-skillzdrive") → find the upload skill
2. listScripts("upload-to-skillzdrive") → get "send-file.sh"
3. getScript("upload-to-skillzdrive", "send-file.sh") → get script with embedded API key
4. Run script LOCALLY: bash send-file.sh --file /path/to/skill.zip
Note: On platforms like claude.ai, whitelist www.skillzdrive.com first.

## Workflow: Manage Collections

- createCollection(name, skillSlugs?) → create new collection
- addToCollection(collectionName, skillSlug) → add one skill
- removeFromCollection(collectionName, skillSlug) → remove one skill
- updateCollection(collectionName, newName) → rename
Collections filter which skills are accessible per API key.

## Workflow: Marketplace Discovery

1. discoverSkills(keywords) → browse marketplace + GitHub skills
2. importToDrive(skillSlug) → import to your drive (charges credits)
3. Optionally addToCollection(collectionName, skillSlug) → organize

## UI Feedback Requirements

Show users what is happening at each stage:
- searchSkills → "Searching for skills..."
- listSkills → "Loading available skills..."
- listScripts → "Loading scripts..."
- runScript → "Running [scriptName]..." with a spinner/progress indicator
- readFile → "Reading results..."
- Success → Display formatted output (code block, file, or rendered content)
- Error → Show error message + first suggestion as recovery action
- "Did you mean X?" → Show typo correction as a clickable option

## Rules (follow strictly)

- NEVER guess skill slugs or script names — always discover via search or list first
- ALWAYS call listScripts before runScript
- ALWAYS use reuseSession: true when calling runScript (output is NOT in the run response)
- ALWAYS read output via readFile after runScript (check /tmp/last_run.out for stdout, /tmp/last_run.err for stderr)
- ALWAYS close sessions when done (they auto-expire after 5 min, but closing frees resources immediately)
- ALWAYS check hasScripts to determine which workflow to follow (script vs template)
- For local-execution skills, use getScript and run from downloadUrl
- Follow _workflow.nextSteps hints in every response for guided navigation
- If a script has requiredEnvVars, the user must configure those API keys in their SkillzDrive account first
- addToCollection/removeFromCollection take a single skillSlug, not an array
- Collections with allowed_skill_ids=null (all skills) reject add/remove operations

## Error Handling

Errors include structured fields:
- error: machine-readable code (skill_not_found, script_not_found, access_denied, etc.)
- message: human-readable text — show this to the user
- suggestions: array of recovery steps — show the first one as an action
- _workflow.nextSteps: what tool to call next for automatic recovery

Common errors:
| Error | Cause | Recovery |
|-------|-------|----------|
| skill_not_found | Bad slug | Check spelling, use searchSkills |
| script_not_found | Wrong name | Call listScripts first, use exact name |
| access_denied | Key restriction | Check API key permissions |
| session_not_found | Session expired | Re-run script with reuseSession: true |
| missing_credentials | User hasn't set up required API key | Direct user to Account settings |
| quota_exceeded | Monthly limit reached | Upgrade plan or wait for reset |

## Verification Checklist

After integrating, confirm each step works:
1. searchSkills("pdf") → returns results with slugs
2. listScripts(slug) → returns script names and descriptions
3. runScript(slug, scriptName, reuseSession: true) → returns sessionId + exitCode 0
4. readFile(sessionId, "/tmp/last_run.out") → returns script output content
5. closeSession(sessionId) → succeeds
6. Bad slug → returns error with suggestions array
7. UI shows loading/success/error states at each stage

## Performance Tips

- Cache listSkills results for the entire session (skills don't change mid-conversation)
- Cache listScripts per skill slug for the session (scripts don't change mid-conversation)
- Don't cache runScript results (each execution is unique)
- Use getResourceInfo before reading large files to check token count
- Use docSection to read specific sections instead of full documentation