marketplace-plugin-creator

Marketplace Plugin Creator

Turn any skill or set of skills into a GitHub-hosted Cowork marketplace plugin that installs and shows up correctly in the Cowork desktop app.

How Cowork Marketplace Plugins Work

When a user enters a GitHub owner/repo in the "Add marketplace" dialog, Cowork:

1. Clones the repo
2. Looks for .claude-plugin/marketplace.json at the repo root — fails if missing
3. Reads the plugins array to find individual plugins
4. For each plugin, reads .claude-plugin/plugin.json for metadata
5. Discovers skills by scanning skills/{skill-name}/SKILL.md directories
6. Discovers commands by scanning commands/{command-name}.md files
7. Caches everything locally under .remote-plugins/ or .local-plugins/cache/

The cached version is what Cowork actually reads. After pushing changes to GitHub, the user must re-sync or uninstall/reinstall for the cache to update.

Required Files

1. .claude-plugin/marketplace.json

This is the marketplace manifest at the repo root. Without it, the "Add marketplace" dialog will show: "This repository isn't a marketplace — no manifest found."

{
  "\$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "marketplace-name",
  "description": "What this marketplace offers",
  "owner": {
    "name": "github-username-or-org"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "What this plugin does",
      "source": "./",
      "category": "productivity",
      "keywords": ["keyword1", "keyword2"]
    }
  ]
}

For a single-plugin marketplace (most common case), set "source": "./" to point at the repo root itself.

For a multi-plugin marketplace, each plugin lives in its own subdirectory:

{
  "plugins": [
    { "name": "plugin-a", "source": "./plugin-a", "description": "..." },
    { "name": "plugin-b", "source": "./plugin-b", "description": "..." }
  ]
}

2. .claude-plugin/plugin.json

This is the plugin manifest — metadata about the individual plugin.

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What this plugin does in detail",
  "author": {
    "name": "Author Name"
  }
}

For single-plugin marketplaces, this goes alongside marketplace.json in the same .claude-plugin/ directory. For multi-plugin marketplaces, each plugin subdirectory has its own .claude-plugin/plugin.json.

3. Skills Directory

Skills must live at skills/{skill-name}/SKILL.md — this is the directory structure Cowork scans to discover skills. A SKILL.md at the repo root will NOT be discovered.

repo-root/
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── skills/
│   └── my-skill-name/
│       ├── SKILL.md
│       ├── scripts/        (optional)
│       └── references/     (optional)
├── commands/               (optional)
│   └── do-thing.md
└── README.md

4. SKILL.md Frontmatter

Every SKILL.md must have YAML frontmatter with name and description:

---
name: skill-identifier
description: >
  What this skill does and when to trigger it. Include specific phrases
  users might say so Claude knows when to activate this skill.
---

# Skill Title

Instructions for Claude go here...

5. Commands (Optional)

Commands go in commands/{command-name}.md with frontmatter:

---
description: What this command does
argument-hint: optional hint for arguments
---

Instructions for Claude when this command is invoked...

Commands show up separately from skills in the plugin UI.

Step-by-Step Process

Converting an existing skill to a marketplace plugin

1. Audit the current structure — check what files exist and where
2. Create .claude-plugin/marketplace.json with the schema above
3. Create .claude-plugin/plugin.json with plugin metadata
4. Move skill files into skills/{skill-name}/ — the directory name becomes the skill identifier. Move SKILL.md, scripts/, references/, and any other supporting files into this subdirectory
5. Clean up root-level duplicates — remove any SKILL.md, scripts/, references/ left at the root after moving them into skills/
6. Remove .skill ZIP files if present — those are a different packaging format and will confuse things
7. Commit and push all changes to GitHub
8. Tell the user to sync the marketplace in Cowork settings

Creating a new marketplace plugin from scratch

1. Ask what the skill should do — understand purpose, triggers, workflow
2. Create the directory structure per the template above
3. Write the SKILL.md with clear frontmatter and instructions
4. Write marketplace.json and plugin.json manifests
5. Initialize git, commit, and push to a GitHub repo
6. Guide the user to add the marketplace in Cowork settings

Common Problems and Fixes

"This repository isn't a marketplace — no manifest found"

Cause: Missing .claude-plugin/marketplace.json at repo root. Fix: Create the file with the marketplace schema.

Plugin installs but shows "This plugin doesn't have any skills or agents"

Cause: One of these issues (check in order):

1. SKILL.md is at the repo root instead of inside skills/{name}/SKILL.md
2. Missing skills/ directory entirely
3. SKILL.md missing frontmatter — needs name and description in YAML front matter
4. Stale cache — Cowork cached an older version of the repo before you added the skills directory. Uninstall and reinstall the plugin to refresh.

Skills show up in a fresh session but not the current one

Cause: Cowork caches plugin content per-session. Changes to the repo only take effect after syncing the marketplace and starting a new Cowork session.

Changes pushed to GitHub aren't reflected

Cause: The local cache under .remote-plugins/ or .local-plugins/cache/ is stale. Fix: Sync the marketplace in plugin settings, or uninstall and reinstall the plugin.

Real-World Example

Here is the exact structure of a working single-skill marketplace plugin:

posthaste-skill/                    (GitHub repo root)
├── .claude-plugin/
│   ├── marketplace.json            (marketplace manifest)
│   └── plugin.json                 (plugin manifest)
├── skills/
│   └── posthaste-file-management/  (skill directory)
│       ├── SKILL.md                (skill instructions + frontmatter)
│       ├── scripts/
│       │   ├── create_project.py
│       │   ├── list_projects.py
│       │   ├── new_template.py
│       │   └── read_template.py
│       └── references/
│           └── template-format.md
├── .gitignore
└── README.md

And its marketplace.json:

{
  "\$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "posthaste-skill",
  "description": "Manage PostHaste project templates and file structures",
  "owner": { "name": "alnutile" },
  "plugins": [
    {
      "name": "posthaste-skill",
      "description": "Manage PostHaste project templates and file structures.",
      "source": "./",
      "category": "productivity",
      "keywords": ["posthaste", "film", "project-management"]
    }
  ]
}

Naming Conventions

• Marketplace name: kebab-case, matches the GitHub repo name
• Plugin name: kebab-case, usually matches marketplace name for single-plugin repos
• Skill directory name: kebab-case, becomes the skill identifier
• SKILL.md name field: kebab-case, should match directory name
• Command filenames: kebab-case .md files, filename becomes the command name