skill-deployer

# Skill Deployer Deploy skills from the sandbox filesystem into a **hosted project UI** - making them visible in the project sidebar, available as slash commands, and persistent across tasks. This is a compatibility adapter; universal cross-AI setups should use `skill-router skill <name>` and OpenSkills-style sync instead. ## How It Works Skills in `/home/ubuntu/skills/` are invisible in many hosted project UIs by default. This skill bridges that gap: 1. **Packages** each skill directory into a `.zip` (SKILL.md + scripts/references at root) 2. **Authenticates** with the provider gRPC-web API using a JWT from the browser session 3. **Uploads** zips to specific projects via `UploadProjectSkill` endpoint 4. Skills then appear in the **project sidebar under "Skills"** and as **slash commands** in new tasks ## Prerequisites Before deploying, two things are needed: **1. JWT Token** — Extract from the browser while the user is logged into the target provider web app: ```javascript // Run via browser_console_exec tool: (document.cookie.split(';').find(c => c.trim().startsWith('session_id=')) || '').split('=').slice(1).join('=') || 'TOKEN_NOT_FOUND' ``` Save to file: `echo "TOKEN" > /tmp/skill_deployer_token.txt` **2. Project UIDs** — Found in the URL when viewing a project: ``` /app/project/<PROJECT_UID> ``` Extract from sidebar via `browser_console_exec` or by clicking each project. ## Commands ### Package Skills (No Upload) Create zip files from all skills in the skills directory: ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --package ``` ### List Skills in a Project See what's currently in a project's UI: ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --project-uid UID --list ``` ### Upload a Single Skill to UI Package and upload one skill by name: ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --project-uid UID --upload-skill skill-name ``` ### Upload All Skills from Zip Directory ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --project-uid UID --upload-dir /tmp/skill_zips ``` ### Delete a Skill from UI ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --project-uid UID --delete-name skill-name ``` ### Sync Project to Exact Skill Set Deletes skills not in the list, uploads missing ones: ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --project-uid UID \ --sync skill-a skill-b skill-c ``` ### Multi-Project Deployment with LLM Curation For deploying curated, domain-relevant skills to multiple projects at once. **Step A — Create projects file** (`projects.json`): ```json { "projects": [ { "name": "My Web App", "uid": "abc123", "context": "Full-stack React + Node web app with auth and database", "tasks": ["frontend dev", "API design", "database queries"], "max_skills": 300 } ] } ``` **Step B — Run LLM curation** (selects universal + domain-specific skills): ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/curate_for_project.py \ --projects projects.json --output deployment_plan.json ``` **Step C — Preview the plan:** ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --plan deployment_plan.json --dry-run ``` **Step D — Deploy to all projects:** ```bash python3 /home/ubuntu/skills/skill-deployer/scripts/deploy_skills.py \ --token "$(cat /tmp/skill_deployer_token.txt)" --plan deployment_plan.json ``` ## Options | Flag | Default | Description | |---|---|---| | `--api-base` | none | Provider API base URL; required for API calls unless `SKILL_DEPLOYER_API_BASE` is set | | `--skills-dir` | `/home/ubuntu/skills` | Source skills directory | | `--zip-dir` | `/tmp/skill_zips` | Directory for packaged zips | | `--rate-limit` | `0.15` | Seconds between API calls | | `--max-retries` | `3` | Retries on 429 rate limit errors | | `--dry-run` | off | Preview changes without executing | ## Limits and Constraints - **500 skills per project** — common provider-enforced hard limit - **Rate limiting** — 429 errors handled with exponential backoff - **Token expiry** — JWT tokens last ~24 hours; re-extract if 401 errors occur - **SKILL.md required** — Zips must contain valid SKILL.md with YAML frontmatter at root ## Troubleshooting | Error | Fix | |---|---| | 401 Unauthorized | Token expired. Re-extract from browser. | | Missing API base | Pass `--api-base https://provider.example` or set `SKILL_DEPLOYER_API_BASE`. | | 429 Rate Limited | Increase `--rate-limit` to 0.3+. | | 500 SKILL_MD_INVALID_FORMAT | Fix SKILL.md YAML frontmatter in the source skill. | | Project limit reached | Max 500. Use curation to select only the best skills. | | Skills not showing in UI | Refresh the project page in browser. Skills appear in sidebar. | ## API Reference Provider endpoint details vary by hosted UI. Use the provider's gRPC-web project-skill API reference when setting `--api-base`.