Plugin to chat skill

Plugin to Chat Skill

A converter and packager for Claude Code / Cowork plugins hosted on GitHub. Pulls a plugin, transforms each of its bundled skills into chat-compliant .skill files, and embeds provenance so the same skill can later be checked for updates.

Important framing for the user. This skill produces .skill files. It cannot auto-install them into claude.ai — that's a manual step (Settings → Capabilities → Skills → Upload). Make that clear in the handoff so the user isn't waiting for something that won't happen.

Dependency. This skill reuses the validator and packaging logic from chat-skill-creator. If chat-skill-creator isn't installed, packaging will fail with a clear error pointing the user at it. If you discover it's missing partway through a conversion, stop and tell the user to install chat-skill-creator first — don't try to vendor a substitute.

When to use this

• The user gives a GitHub URL pointing at a Claude Code plugin (a directory containing .claude-plugin/plugin.json).
• The user asks to "install" or "use" a plugin from GitHub in claude.ai chat.
• The user has previously converted a plugin and wants to check for updates / re-pull.
• The user supplies a marketplace-style URL containing several plugins and wants one (or all) converted.

Do not trigger when the user wants to write a new skill from scratch — that's chat-skill-creator. This skill is specifically for ingesting existing Claude Code plugin sources.

Pipeline

The conversion runs in five stages. Each is implemented by a bundled script that you should use rather than reimplementing inline.

GitHub URL → fetch → discover plugins → per-skill convert
           → analyse dependencies & description quality (auto, in convert)
           → enrich weak descriptions (Claude-in-the-loop)
           → validate → package (.skill)

Stage 1 — Fetch

python -m scripts.fetch_plugin <github-url> /home/claude/_plugin_src

Uses shallow sparse-checkout via git. Writes the source tree under /home/claude/_plugin_src/ and prints a JSON line with the commit SHA, plugin path, and source URL. Always capture this stdout — its fields go into every converted skill's provenance block.

If the URL points at a single plugin (the path contains .claude-plugin/plugin.json), the script returns one entry. If it points at a directory containing multiple plugins (marketplace pattern), it returns all of them. Ask the user which one(s) they want when there's more than one and the request was ambiguous; default to all when they said something like "install this whole marketplace".

Stage 2 — Convert (with dependency + quality analysis)

For each plugin selected, run:

python -m scripts.convert_plugin <plugin-src-dir> /home/claude/_converted --source-url <url> --commit <sha>

This iterates over <plugin-src-dir>/skills/*/ and writes one chat-compliant skill directory per source skill into /home/claude/_converted/. It also writes a conversion-report.md that now includes:

• Per-skill cross-references — which other skills in the same plugin this one mentions, plus the reverse index (who references it).
• Inbound commands — slash commands from the source plugin that referenced this skill (joined back from the dropped-commands list). These are the best source material for description enrichment because the command description was specifically written to invoke this skill.
• Description quality assessment — every skill is tagged good, weak, or missing, with specific reason markers (short, no_trigger_phrase, vague_opener, placeholder_inserted, no_sentence_punctuation).

Always read the conversion report before moving on. Surface anything significant to the user — dropped artefacts, broken cross-references (a skill mentions a name that doesn't exist in the converted set), and the list of enrichment candidates.

Stage 3 — Enrich weak descriptions

For each skill flagged weak or missing in the report, rewrite the description in /home/claude/_converted/<skill-name>/SKILL.md using these inputs, in priority order:

1. The inbound command descriptions (from the report's "Description quality — enrichment candidates" section). These were written by the plugin author to describe exactly when the skill should fire, so they're the cleanest trigger material.
2. The skill body itself — read /home/claude/_converted/<skill-name>/SKILL.md and the first README-like paragraph. Extract concrete nouns (what it operates on) and verbs (what it produces).
3. Cross-references from other skills — if skill A's body says "first run the <weak-skill> skill to do X", that "to do X" is real signal.

Rewrite to match the chat-skill description shape: a sentence stating when to use it (trigger phrases), a sentence stating what it produces, and ideally an explicit "Use this skill whenever / Triggers on" opener. Keep under 1024 chars. Don't invent functionality not in the source — if the body is genuinely thin, write a thin-but-honest description and tell the user the underlying skill is weak.

Edit the SKILL.md frontmatter's description: field directly. Don't touch the provenance block, body, or other frontmatter keys. Skip skills already tagged good.

If the user says "don't enrich, just convert as-is", skip this stage and tell them which skills will likely trigger poorly so they know what they're trading.

Stage 4 — Validate

python /mnt/skills/user/chat-skill-creator/scripts/quick_validate.py /home/claude/_converted/<skill-name>

This calls chat-skill-creator's validator directly — same rules the skill-creator skill uses on its own output, so a plugin-converted skill is held to the same bar as a hand-authored one. If anything fails (including a description you just enriched that went over 1024 chars), fix it and re-validate. Don't skip this step; descriptions exceeding 1024 chars or names that don't match the directory will silently break triggering when installed.

If the path above doesn't exist, chat-skill-creator isn't installed in this workspace. Stop the pipeline and tell the user to install it first; do not paper over by writing a local validator.

Stage 5 — Package

python -m scripts.package_skill /home/claude/_converted/<skill-name> /mnt/user-data/outputs

Produces <skill-name>.skill (a zip) in /mnt/user-data/outputs/. Repeat for each converted skill. End with a single present_files call listing every .skill file, with the most important one first.

Handling the "install" vs "update" cases

Both paths run the same pipeline; the difference is what you do with the outputs and what you tell the user.

Install (first time):

1. Run the pipeline.
2. Hand over all .skill files via present_files.
3. Briefly tell the user: "Install each by going to Settings → Capabilities → Skills → Upload. The provenance is embedded so I can check for updates later."

Update (re-fetch):

1. If the user uploaded the previous .skill files, read the provenance comment in each (it's an HTML comment block at the top of SKILL.md inside the zip) to confirm the source URL and previous commit SHA.
2. Run the pipeline to regenerate.
3. Diff by commit SHA, not by content. If the source commit hasn't moved since the previous install, tell the user there are no updates and don't re-emit. If it has, emit only the skills whose SKILL.md content actually changed (compare against the unzipped previous versions); silently skipping unchanged skills reduces user friction.
4. In the handoff, name which skills changed and why if you can tell from commit history.

If the user just says "update the PE plugin" without supplying old .skill files, you can't diff — just regenerate everything and tell the user that's what you did.

What gets converted (and how)

See references/conversion-rules.md for the full table. Headline rules:

• skills/<name>/SKILL.md → converted to YAML-frontmatter format, kebab-case name field set from directory name, description: line in the body extracted into the frontmatter, provenance block prepended. Body otherwise preserved.
• skills/<name>/scripts/, references/, assets/ → copied verbatim. Bundled resources transfer cleanly to the chat sandbox.
• commands/*.md → dropped. These are slash-command shortcuts that don't exist in chat. The conversion report lists each command and notes which skill it referenced so the user knows what's gone.
• hooks/hooks.json → dropped if non-empty (warn in report); silently dropped if empty.
• .claude-plugin/plugin.json → read for version + plugin name, then dropped.
• MCP server configs (if present) → dropped, reported. Chat skills can't bring their own MCP wiring.
• Subagent definitions → dropped, reported. The chat sandbox is single-agent.

Read references/conversion-rules.md if the source plugin has anything unusual (custom directories, manifest fields the converter doesn't recognise, or skills already in chat-compliant format).

When the source skill is already chat-compliant

Some plugin skills already use proper YAML frontmatter (---\nname: x\ndescription: y\n---). The converter detects this and preserves the existing frontmatter, only adding the provenance block. Don't re-write descriptions in this case — the original author's wording is presumed correct.

Limitations and honest disclosure

Tell the user about these when handing over the converted output. Do not gloss:

• No auto-install. They upload via Settings.
• Commands are gone. If they relied on /dd-checklist in Claude Code, they now invoke by natural language ("dd checklist for X") which is what the skill description triggers on anyway. Where a command existed, its description was used as enrichment material — so triggering should be reasonable.
• Hooks, subagents, MCP wiring are gone. Most PE-style plugins don't use these, but check the report.
• Cross-skill references are documentation, not invocation. The converter detects when one skill's body mentions another and surfaces this in the report, but chat skills don't compose programmatically — a phrase like "first run the X skill" remains as prose for the user/Claude to act on.
• Description enrichment is best-effort. If the source body is genuinely thin and no commands referenced the skill, the enriched description will still be modest. Tell the user; offer to run it through chat-skill-creator's description-tightening pass if they want a deeper rewrite.

Output template for the user-facing handoff

After packaging, your final message should follow roughly this structure (adapt to the specific case):

Done. Converted the **<plugin name>** plugin (<plugin version>, commit <sha>) into <N> chat skills.

Files (install each via Settings → Capabilities → Skills → Upload):
- <skill-1>.skill — <one-line what it does>
- <skill-2>.skill — <one-line what it does>
…

Dropped during conversion:
- <commands list, if any>
- <hooks/MCP/subagents, if any>

The provenance is embedded in each skill. To check for updates later, just say "check the <plugin name> plugin for updates" and supply the same source URL (or re-upload the .skill files).

Keep it concise. The user wants the files and the install instruction. Long postambles get skimmed.