Short answer: start with a standalone skill. Move to a plugin only when you need to ship several parts (skills, connectors, commands, agents) as one unit, or give teammates the same setup with versioned updates. Check where each piece loads first, because the documentation shows that surfaces differ. For Claude Duet, the announcement says it carries over your skills and can use Claude Marketplace connectors and plugins; no page we found documents uploading a custom skill or plugin into Duet, so treat that as unverified.
Status: documentation review, not hands-on tested. This article is about packaging your own workflow; for definitions of skills, plugins and connectors see the guide. Labels: Vendor documentation, Practitioner report (self-reported, not checked), Researcher recommendation (this guide’s judgement).
Prerequisites
- A procedure you have already done by hand several times, so you know the real inputs and failure points.
- A list of the surfaces your users actually use (claude.ai, Claude Code, Cowork, the API, or Duet) and their plans.
- Somewhere to keep the files under version control, and a named owner for updates.
- Willingness to read every bundled file before sharing it.
Four questions that decide it
1. Is it one procedure or a bundle? Vendor documentation: “Skills, subagents, hooks, and MCP servers all work on their own, without a plugin”, and a plugin is for when you want several of them “packaged as one unit”. The plugin README format is file-based: “markdown and JSON, no code, no infrastructure, no build steps”. One procedure with no connectors is a skill.
2. Who needs it, and on which surface? Sharing scope depends on where the skill lives. Per the Agent Skills overview: custom skills in claude.ai are “individual to each user” and not centrally managed; on the API they are “shared workspace-wide”; in Claude Code they are personal or project-based and “can also be shared through Claude Code Plugins”. The same page says “custom Skills do not sync across surfaces”. Cowork and cloud sessions don’t read ~/.claude/skills/ on your machine; a plugin installed on your account appears in Claude Code as a synced plugin at the next session start, while one installed from the command line stays on that machine.
3. Does every surface load every component? The platform support table says a surface skips components it doesn’t load, “so a plugin can look complete in one place and partial in another”. Agents are ignored in chat but load in Cowork and Claude Code; a top-level bin/ directory can’t be installed in chat or Cowork.
4. What does it cost, and who reviews it? An enabled plugin puts each invocable skill’s name and description in Claude’s context on every turn, and “what the plugin runs, it runs as you”. Anthropic’s directory review doesn’t cover a plugin you add from a marketplace URL or upload yourself. The skills overview advises using skills only from sources you trust.
The workflow
-
Write the procedure as plain steps with inputs, outputs and a stop condition (“if the notes file is missing, ask; do not invent”). Researcher recommendation.
-
Make it a standalone skill. A skill is a folder with a
SKILL.md; the description should say what it does and when to use it. In Claude Code the combined listing text per skill is capped at 1,536 characters, and malformed frontmatter means Claude can’t match the description. Illustrative frontmatter, not observed output and not run:--- name: weekly-client-summary description: Draft the weekly client summary from the notes file. Use when the user asks for the weekly summary or status update for a client. --- -
Compare against a baseline. The Claude Code docs say that seeing a skill trigger “tells you Claude found it, not that it did what you intended”, and suggest running realistic prompts in a fresh session with the skill on and off. The agentskills.io guide uses the same with/without pattern and says verification scripts are more reliable than LLM judgment for mechanical checks. Anthropic’s skill-creator names data extraction and fixed workflow steps as outputs that benefit from test cases.
-
Package as a plugin only when a trigger is met: you need a connector or command shipped with the skill; several people need identical setup; you want versioned releases. The Claude Code docs list sharing with teammates, installing in many projects and publishing versioned releases as reasons to make a plugin.
-
Choose a distribution route. Options in the documentation: commit
.claude/skills/to version control, add a plugin, or deploy through managed settings. On Team and Enterprise plans, an Owner sets each plugin to Not available, Available to install, Installed by default, or Required. -
Test on every surface you claim. If you say “works in Cowork”, load it in Cowork.
What practitioners report (not verified)
Practitioner report. A LinkedIn article dated 2026-02-23 says shared skills live in a private GitHub repo distributed through Claude Code’s plugin marketplace system, and lists gaps: “there’s no package.json equivalent for Claude skills yet”, a CLAUDE.md note acting as a “soft contract” because Claude “can’t auto-install missing plugins”, and a CODEOWNERS file for ownership. Treat these as one team’s experience in Claude Code at that date; check current docs. A separate LinkedIn explainer frames a plugin as “a bundle”, which matches the vendor definition. Two YouTube descriptions argue the terms are not interchangeable and that installing the same set into Code and Cowork yields “two mediocre stacks instead of two sharp ones”. Those are opinions read from descriptions; we did not watch the videos or retrieve transcripts.
Validation and rejection checklist
Package it only if:
- the procedure produced acceptable output on realistic prompts against a no-skill baseline;
- you can name the surface where each user will run it, and you checked that surface’s component support;
- someone owns updates, and users know how they receive them;
- you read every bundled file, script and connector reference as if installing software.
Do not package it as a plugin if it is one personal procedure, if it needs components your target surface ignores, or if nobody will review changes.
Failure cases
- Skill never triggers. The description lacks the words users say; the docs list troubleshooting steps.
- Skill triggers too often. Make the description more specific, or require manual invocation.
- “It worked on my machine.” The skill sat in
~/.claude/skills/, which Cowork and cloud sessions don’t read. - Looks complete, runs partial. Agents or hooks ignored on a surface.
- Context tax. Many enabled plugins add descriptions to every turn.
- Connector expectations. Adding a plugin doesn’t add a connector or sign you in.
Compatibility: Duet versus the Claude ecosystem
| Surface | Custom skill | Plugin | Evidence |
|---|---|---|---|
| claude.ai | Zip upload in Settings > Features; individual user | Added via Customize > Plugins | Skills overview; plugins page |
| Claude API | Workspace-wide | Not covered in these pages | Skills overview |
| Claude Code | Personal, project, or via plugin | Marketplace or --plugin-dir |
Skills and plugins docs |
| Cowork | Loads skills enabled on the claude.ai account | Loads skills, commands, agents and hooks | Skills page; support table |
| Claude Duet | Announcement: “carries over your memory, skills, and connected apps from your Claude account”. No documented upload or install path found. | Announcement: can use “the over 6,000 connectors and plugins in the Claude Marketplace”. Component support not documented. | Not tested |
Two cautions. Claude Code’s docs state that a plugin marketplace isn’t Claude Marketplace, so a self-hosted /plugin marketplace add repository should not be assumed to appear in Duet (researcher inference). And one early reviewer says Duet’s scheduled runs can’t reach custom connectors (single early-access impression, partly paywalled), so a plugin that depends on a custom connector deserves extra scepticism there.