| name | convert-skills |
| description | Use when the user wants to install third-party Agent Skills into Claude Cowork — especially when they give you a GitHub URL like coreyhaines31/marketingskills or mattpocock/skills and want it as an installable Cowork plugin. Produces a strictly canonical .plugin file that matches anthropics/knowledge-work-plugins format, ready for Cowork's "Upload local plugin" UI. |
| compatibility | Designed for Claude Cowork (with code execution). Also runs in Claude Code. |
Convert Skills to a Cowork-Installable .plugin File
The user wants to install Agent Skills (folders with SKILL.md) into Claude Cowork. Cowork's "Upload local plugin" UI requires a .plugin file that strictly matches the canonical schema documented in anthropics/knowledge-work-plugins. This skill produces that file.
When to use
- User gives a GitHub URL or
owner/repo and says "make this a Cowork plugin"
- User has a local folder of skills and wants to install them in Cowork
- User wants to upload individual skills to claude.ai instead of a whole plugin
Primary path — GitHub URL → .plugin file
bash ${CLAUDE_PLUGIN_ROOT}/skills/convert-skills/scripts/from-github.sh \
<owner/repo-or-full-url> [plugin-name] [skills-subpath]
Examples:
bash ${CLAUDE_PLUGIN_ROOT}/skills/convert-skills/scripts/from-github.sh coreyhaines31/marketingskills marketing-skills
bash ${CLAUDE_PLUGIN_ROOT}/skills/convert-skills/scripts/from-github.sh mattpocock/skills pocock-skills
Skills are discovered recursively, so both flat (skills/<name>/) and category-nested (skills/<category>/<name>/) layouts work. Output goes to ~/outputs/ if it exists (Cowork's outputs folder — file appears as a rich preview with an Install button), otherwise ./out/.
Always validate before declaring success
After producing the .plugin file, run the validator and report the result to the user:
bash ${CLAUDE_PLUGIN_ROOT}/skills/convert-skills/scripts/validate.sh <path-to-.plugin>
If validation reports errors, fix them before telling the user to upload.
Tell the user how to install the result
Open the Claude Desktop app → Cowork tab → Customize (left sidebar) → Upload local plugin and select the .plugin file.
What the script enforces (matches Cowork's documented schema)
plugin.json contains exactly: name, version, description, author.name. No skills field, no license field — those are Claude Code conventions Cowork's validator may reject.- Each
SKILL.md frontmatter is rewritten to contain only name and description — Claude Code-only fields like disable-model-invocation, allowed-tools, model, compatibility are stripped.
- The
name field in each SKILL.md is forced to match the folder name (required by Cowork's validator).
- Skill names containing
claude-code are auto-renamed (Cowork's validator rejects these — confirmed by bisection on mattpocock/skills's git-guardrails-claude-code). The substring is stripped and surrounding hyphens collapsed: git-guardrails-claude-code → git-guardrails.
- A
README.md is generated at the plugin root listing all bundled skills.
.claude-plugin/plugin.json is at the archive root (not nested inside a wrapper folder).- File extension is
.plugin (Cowork rejects .zip).
Alternative path — per-skill zips for claude.ai
When the user wants to upload skills one-by-one via claude.ai → Settings → Capabilities → Skills → Upload:
bash ${CLAUDE_PLUGIN_ROOT}/skills/convert-skills/scripts/pack-skill.sh \
<source-skills-dir> <output-dir>
Common failure modes
- "Plugin validation failed" in Cowork — run
validate.sh on the produced file and report all errors. The most common cause used to be Claude Code-specific frontmatter fields; the script now strips them automatically.
- "no SKILL.md found anywhere" — the repo URL is wrong or contains no skills.
- macOS
.DS_Store files inside the .plugin — script excludes them automatically.
