agentleFS
laurigateslaurigates/claude-plugins/.claude/skills/marketplace-authoring/SKILL.md

marketplace-authoring

Skill60 starsChanged yesterdayMITView on GitHub

Add, modify, or delete a skill or plugin in this repo — frontmatter shape, the seven metadata files a plugin touches, and the create/delete checklists. Use when creating a new skill or plugin, removing one, or asking which files a plugin change must update.

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 10 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create skill directory: mkdir -p <plugin>/skills/<skill-name>

    line 32
  2. Very specific:

    Create skill.md with YAML frontmatter:

    line 33
  3. Distinctive:

    Follow content structure: Core Expertise → Commands → Patterns → Quick Reference

    line 44
  4. Distinctive:

    Update all metadata files (see Plugin Lifecycle section)

    line 46
  5. Distinctive:

    When creating, modifying, or deleting a plugin, update these files:

    line 81
  6. Distinctive:

    Create plugin directory structure (see Project Structure in CLAUDE.md)

    line 101
  7. Distinctive:

    Create README.md with plugin documentation

    line 118
  8. Very specific:

    Add entry to .claude-plugin/marketplace.json (under the plugins array), carrying the same author, license and repository as the plugin's …

    line 119
  9. Very specific:

    Remove entry from .claude-plugin/marketplace.json

    line 167
  10. Very specific:

    Remove package from release-please-config.json

    line 168
  11. Very specific:

    Remove version from .release-please-manifest.json

    line 169
  12. Very specific:

    Remove the <plugin>@laurigates-claude-plugins key from .claude/settings.json enabledPlugins

    line 170
  13. Distinctive:

    Research documentation: - Use context7, web search

    line 174
  14. Distinctive:

    Write skills: - Follow standard structure

    line 176
  15. Very specific:

    Commit early: - Use conventional commit format (see .claude/rules/conventional-commits.md)

    line 178
  16. Distinctive:

    Test: - Verify skills load and work

    line 179
  17. Distinctive:

    Create PR: - Use conventional commit format for title (drives automation)

    line 180
  18. Distinctive:

    After a plugin add or delete, the two guards that catch dangling metadata:

    line 184

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/marketplace-authoring

The authoring procedures for this marketplace: how to create a skill, how to create a plugin, what to update when either changes, and how to delete one without leaving dangling metadata.

Promoted out of CLAUDE.md (issue #2140) because all four are procedures with a clear trigger — they do not need to be resident when the user is debugging a hook. CLAUDE.md keeps only the repo blurb, the rules index, and the gotchas.

Detailed patterns live in the rules this skill names; it is the sequence, not a second copy of them.

Creating New Skills

See .claude/rules/skill-development.md for detailed patterns.

Note (Claude Code 2.1.157): plugins placed in .claude/skills are now auto-loaded without a marketplace entry — handy for local or quick one-off plugins. This repo's published plugins still use the full marketplace + release-please lifecycle described in Plugin Lifecycle below.

Quick Start

  1. Create skill directory: mkdir -p <plugin>/skills/<skill-name>
  2. Create skill.md with YAML frontmatter:
    ---
    name: <Skill Name>
    description: <1-2 sentence description>
    allowed-tools: Bash, Read, Grep, Glob, TodoWrite
    created: YYYY-MM-DD
    modified: YYYY-MM-DD
    reviewed: YYYY-MM-DD
    ---
  3. Follow content structure: Core Expertise → Commands → Patterns → Quick Reference
  4. Include agentic optimizations table
  5. Update all metadata files (see Plugin Lifecycle section)

Skill Granularity Decision

Choose...When...
Single skillOperations are related and share context
Multiple skillsDistinct workflows, different user intents

Example: bun-package-manager (deps) vs bun-development (run/test/build)

Creating User-Invocable Skills

Skills are invocable via /plugin:skill-name syntax. See .claude/rules/skill-naming.md for naming conventions.

  1. Create skill directory: mkdir -p <plugin>/skills/<skill-name>
  2. Create SKILL.md with YAML frontmatter:
    ---
    name: <skill-name>
    description: What it does. Use when...
    args: <arg-spec>
    allowed-tools: Bash, Read
    argument-hint: human hint
    created: YYYY-MM-DD
    modified: YYYY-MM-DD
    reviewed: YYYY-MM-DD
    ---
  3. Include: Context → Execution → Post-actions

Plugin Lifecycle

Files to Update

When creating, modifying, or deleting a plugin, update these files:

FileLocationAction
plugin.json<plugin>/.claude-plugin/plugin.jsonCreate/update plugin manifest
README.md<plugin>/README.mdCreate/update plugin documentation
marketplace.json.claude-plugin/marketplace.jsonAdd/update/remove plugin entry
release-please-config.jsonRootAdd/remove plugin package config
.release-please-manifest.jsonRootAdd/remove plugin version entry
PLUGIN-MAP.mddocs/PLUGIN-MAP.mdAdd/remove plugin from navigation map
settings.json.claude/settings.jsonAdd/remove the plugin in enabledPlugins (<plugin>@laurigates-claude-plugins) — enforced by the Plugin: Enablement drift check

docs/CATALOG.md is generated from marketplace.json and the plugin dirs, so it is not on this list: the generate-catalog pre-commit hook rewrites it, or run just catalog. CI fails a PR whose committed catalog is stale.

Creating a New Plugin

Quick scaffold (Claude Code 2.1.157): claude plugin init <name> scaffolds a new plugin in .claude/skills (auto-loaded, no marketplace entry needed). Use it for local/quick plugins; for plugins published from this repo, follow the full marketplace + release-please steps below.

  1. Create plugin directory structure (see Project Structure in CLAUDE.md)
  2. Create .claude-plugin/plugin.json:
    {
      "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
      "name": "new-plugin",
      "version": "1.0.0",
      "description": "Plugin description",
      "author": {
        "name": "Lauri Gates"
      },
      "license": "MIT",
      "repository": "https://github.com/laurigates/claude-plugins",
      "keywords": ["keyword1", "keyword2"]
    }
    license (from the allowlist ["MIT"]), author.name and repository are required here and in the marketplace entry below (homepage is deliberately omitted, #2772); bash scripts/plugin-compliance-check.sh --license-only fails the PR without them. The repo-root MIT LICENSE covers every plugin, so no per-plugin LICENSE file is needed.
  3. Create README.md with plugin documentation
  4. Add entry to .claude-plugin/marketplace.json (under the plugins array), carrying the same author, license and repository as the plugin's plugin.json:
    {
      "name": "new-plugin",
      "source": "./new-plugin",
      "description": "Plugin description",
      "version": "1.0.0",
      "author": {
        "name": "Lauri Gates"
      },
      "license": "MIT",
      "repository": "https://github.com/laurigates/claude-plugins",
      "keywords": ["keyword1", "keyword2"],
      "category": "category-name"
    }
    Note: marketplace.json has structure { "name": "...", "plugins": [...] } — add to the plugins array. python3 scripts/sync-plugin-configs.py --fix generates this entry from the manifest.
  5. Add to release-please-config.json:
    "new-plugin": {
      "component": "new-plugin",
      "release-type": "simple",
      "extra-files": [
        {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"},
        {"type": "json", "path": "/.claude-plugin/marketplace.json", "jsonpath": "$.plugins[?(@.name=='new-plugin')].version"}
      ],
      "changelog-sections": [
        {"type": "feat", "section": "Features"},
        {"type": "fix", "section": "Bug Fixes"},
        {"type": "perf", "section": "Performance"},
        {"type": "refactor", "section": "Code Refactoring"},
        {"type": "docs", "section": "Documentation"}
      ]
    }
  6. Add to .release-please-manifest.json:
    "new-plugin": "1.0.0"
  7. Enable it in .claude/settings.json so the repo dogfoods it:
    "enabledPlugins": { "new-plugin@laurigates-claude-plugins": true }
    The Plugin: Enablement drift check (scripts/check-enabled-plugins-drift.sh) fails CI if a marketplace plugin is left disabled.

Deleting a Plugin

  1. Remove plugin directory
  2. Remove entry from .claude-plugin/marketplace.json
  3. Remove package from release-please-config.json
  4. Remove version from .release-please-manifest.json
  5. Remove the <plugin>@laurigates-claude-plugins key from .claude/settings.json enabledPlugins

Development Workflow

  1. Research documentation - Use context7, web search
  2. Plan skill structure - Decide granularity, scope
  3. Write skills - Follow standard structure
  4. Update all metadata files - See Plugin Lifecycle section
  5. Commit early - Use conventional commit format (see .claude/rules/conventional-commits.md)
  6. Test - Verify skills load and work
  7. Create PR - Use conventional commit format for title (drives automation)

Verify

After a plugin add or delete, the two guards that catch dangling metadata:

bash scripts/check-docs-index.sh
bash scripts/plugin-compliance-check.sh

check-docs-index.sh cross-checks the plugin set and per-plugin skill/agent counts against disk across README.md, docs/PLUGIN-MAP.md, and the d2 diagram — use /docs-refresh to repair count drift it reports. It also gates two name-level invariants at ERROR severity (--strict therefore fails CI): the committed docs/diagrams/plugin-relationships.svg must render the same per-plugin labels its .d2 source states (re-render with d2 docs/diagrams/plugin-relationships.d2 docs/diagrams/plugin-relationships.svg — never hand-edit the .svg), and every leading-cell /<ns>:<name> row in a plugin README must resolve to a skill directory (#2453).

Related

  • .claude/rules/skill-development.md — skill creation patterns
  • .claude/rules/skill-naming.md — namespace conventions for user-invocable skills
  • .claude/rules/skill-quality.md — size limits, required sections, quality checklist
  • .claude/rules/plugin-structure.md — plugin.json schema and directory layout
  • .claude/rules/release-please.md — version management and changelog automation
  • .claude/rules/conventional-commits.md — the commit/PR-title format that drives release-please
  • .claude/rules/skill-consolidation.md — merging or deleting skills (distinct from the plugin-level checklist here)
  • /docs-refresh — repairs catalog count drift after a skill or plugin lands

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.