convert-skills

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.