agentleFS
freightCognitionfreightCognition/linehaulai-claude-marketplace/CLAUDE.md

linehaulai-claude-marketplace

CLAUDE.md4 starsChanged 51 days agoMITView on GitHub

Official Marketplace Documentation to Follow: Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities. A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community. Looking to install plugins from an existing marketplace? See Discover…

The file

Show its rules and text

We split this CLAUDE.md into the rules it gives an agent

20 rules. About 0 are common, 10 are distinctive, and 10 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.

  • 10

    Very specific

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

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

    Create a Markdown file that defines what the /review command does.

    line 36
  2. Very specific:

    Create a plugin.json file that describes the plugin.

    line 50
  3. Distinctive:

    Create the marketplace catalog that lists your plugin.

    line 62
  4. Distinctive:

    Add the marketplace and install the plugin.

    line 82
  5. Very specific:

    How plugins are installed: When users install a plugin, Claude Code copies the plugin directory to a cache location.

    line 102
  6. Distinctive:

    If you need to share files across plugins, use symlinks (which are followed during copying) or restructure your marketplace so the shared …

    line 104
  7. Very specific:

    Create .claude-plugin/marketplace.json in your repository root.

    line 109
  8. Very specific:

    ${CLAUDE_PLUGIN_ROOT}: Use this variable in hooks and MCP server configs to reference files within the plugin's installation directory.

    line 300
  9. Very specific:

    Add marketplace file: Create .claude-plugin/marketplace.json with your plugin definitions

    line 310
  10. Distinctive:

    Test your marketplace locally before sharing:

    line 325
  11. Very specific:

    When strictKnownMarketplaces is configured in managed settings, the restriction behavior depends on the value:

    line 368
  12. Distinctive:

    Test your marketplace before sharing.

    line 423
  13. Distinctive:

    Add the marketplace for testing:

    line 437
  14. Distinctive:

    Verify the marketplace URL is accessible

    line 459
  15. Very specific:

    Check that .claude-plugin/marketplace.json exists at the specified path

    line 460
  16. Very specific:

    Ensure JSON syntax is valid using claude plugin validate or /plugin validate

    line 461
  17. Very specific:

    Run claude plugin validate .

    line 466
  18. Distinctive:

    Verify plugin source URLs are accessible

    line 487
  19. Distinctive:

    Check that plugin directories contain required files

    line 488
  20. Distinctive:

    Test plugin sources manually by cloning/downloading

    line 490

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md 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
CLAUDE.md

Official Marketplace Documentation to Follow:

Create and distribute a plugin marketplace

Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.

A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.

Looking to install plugins from an existing marketplace? See Discover and install prebuilt plugins.

Overview

Creating and distributing a marketplace involves:

  1. Creating plugins: build one or more plugins with commands, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see Create plugins for details on how to create them.
  2. Creating a marketplace file: define a marketplace.json that lists your plugins and where to find them (see Create the marketplace file).
  3. Host the marketplace: push to GitHub, GitLab, or another git host (see Host and distribute marketplaces).
  4. Share with users: users add your marketplace with /plugin marketplace add and install individual plugins (see Discover and install plugins).

Once your marketplace is live, you can update it by pushing changes to your repository. Users refresh their local copy with /plugin marketplace update.

Walkthrough: create a local marketplace

This example creates a marketplace with one plugin: a /review command for code reviews. You'll create the directory structure, add a slash command, create the plugin manifest and marketplace catalog, then install and test it.

<Steps> <Step title="Create the directory structure"> ```bash theme={null} mkdir -p my-marketplace/.claude-plugin mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin mkdir -p my-marketplace/plugins/review-plugin/commands ``` </Step> <Step title="Create the plugin command"> Create a Markdown file that defines what the `/review` command does.
```markdown my-marketplace/plugins/review-plugin/commands/review.md theme={null}
Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.
```
</Step> <Step title="Create the plugin manifest"> Create a `plugin.json` file that describes the plugin. The manifest goes in the `.claude-plugin/` directory.
```json my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json theme={null}
{
  "name": "review-plugin",
  "description": "Adds a /review command for quick code reviews",
  "version": "1.0.0"
}
```
</Step> <Step title="Create the marketplace file"> Create the marketplace catalog that lists your plugin.
```json my-marketplace/.claude-plugin/marketplace.json theme={null}
{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./plugins/review-plugin",
      "description": "Adds a /review command for quick code reviews"
    }
  ]
}
```
</Step> <Step title="Add and install"> Add the marketplace and install the plugin.
```shell  theme={null}
/plugin marketplace add ./my-marketplace
/plugin install review-plugin@my-plugins
```
</Step> <Step title="Try it out"> Select some code in your editor and run your new command.
```shell  theme={null}
/review
```
</Step> </Steps>

To learn more about what plugins can do, including hooks, agents, MCP servers, and LSP servers, see Plugins.

<Note> **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.

If you need to share files across plugins, use symlinks (which are followed during copying) or restructure your marketplace so the shared directory is inside the plugin source path. See Plugin caching and file resolution for details. </Note>

Create the marketplace file

Create .claude-plugin/marketplace.json in your repository root. This file defines your marketplace's name, owner information, and a list of plugins with their sources.

Each plugin entry needs at minimum a name and source (where to fetch it from). See the full schema below for all available fields.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace schema

Required fields

FieldTypeDescriptionExample
namestringMarketplace identifier (kebab-case, no spaces). This is public-facing: users see it when installing plugins (for example, /plugin install my-tool@your-marketplace)."acme-tools"
ownerobjectMarketplace maintainer information (see fields below)
pluginsarrayList of available pluginsSee below
<Note> **Reserved names**: The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names that impersonate official marketplaces (like `official-claude-plugins` or `anthropic-tools-v2`) are also blocked. </Note>

Owner fields

FieldTypeRequiredDescription
namestringYesName of the maintainer or team
emailstringNoContact email for the maintainer

Optional metadata

FieldTypeDescription
metadata.descriptionstringBrief marketplace description
metadata.versionstringMarketplace version
metadata.pluginRootstringBase directory prepended to relative plugin source paths (for example, "./plugins" lets you write "source": "formatter" instead of "source": "./plugins/formatter")

Plugin entries

Each plugin entry in the plugins array describes a plugin and where to find it. You can include any field from the plugin manifest schema (like description, version, author, commands, hooks, etc.), plus these marketplace-specific fields: source, category, tags, and strict.

Required fields

FieldTypeDescription
namestringPlugin identifier (kebab-case, no spaces). This is public-facing: users see it when installing (for example, /plugin install my-plugin@marketplace).
sourcestring|objectWhere to fetch the plugin from (see Plugin sources below)

Optional plugin fields

Standard metadata fields:

FieldTypeDescription
descriptionstringBrief plugin description
versionstringPlugin version
authorobjectPlugin author information (name required, email optional)
homepagestringPlugin homepage or documentation URL
repositorystringSource code repository URL
licensestringSPDX license identifier (for example, MIT, Apache-2.0)
keywordsarrayTags for plugin discovery and categorization
categorystringPlugin category for organization
tagsarrayTags for searchability
strictbooleanControls whether plugins need their own plugin.json file. When true (default), the plugin source must contain a plugin.json, and any fields you add here in the marketplace entry get merged with it. When false, the plugin doesn't need its own plugin.json; the marketplace entry itself defines everything about the plugin. Use false when you want to define simple plugins entirely in your marketplace file.

Component configuration fields:

FieldTypeDescription
commandsstring|arrayCustom paths to command files or directories
agentsstring|arrayCustom paths to agent files
hooksstring|objectCustom hooks configuration or path to hooks file
mcpServersstring|objectMCP server configurations or path to MCP config
lspServersstring|objectLSP server configurations or path to LSP config

Plugin sources

Relative paths

For plugins in the same repository:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

GitHub repositories

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Git repositories

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Advanced plugin entries

This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Key things to notice:

  • commands and agents: You can specify multiple directories or individual files. Paths are relative to the plugin root.
  • ${CLAUDE_PLUGIN_ROOT}: Use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed.
  • strict: false: Since this is set to false, the plugin doesn't need its own plugin.json. The marketplace entry defines everything.

Host and distribute marketplaces

Host on GitHub (recommended)

GitHub provides the easiest distribution method:

  1. Create a repository: Set up a new repository for your marketplace
  2. Add marketplace file: Create .claude-plugin/marketplace.json with your plugin definitions
  3. Share with teams: Users add your marketplace with /plugin marketplace add owner/repo

Benefits: Built-in version control, issue tracking, and team collaboration features.

Host on other git services

Any git hosting service works, such as GitLab, Bitbucket, and self-hosted servers. Users add with the full repository URL:

/plugin marketplace add https://gitlab.com/company/plugins.git

Test locally before distribution

Test your marketplace locally before sharing:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

For the full range of add commands (GitHub, Git URLs, local paths, remote URLs), see Add marketplaces.

Require marketplaces for your team

You can configure your repository so team members are automatically prompted to install your marketplace when they trust the project folder. Add your marketplace to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

You can also specify which plugins should be enabled by default:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

For full configuration options, see Plugin settings.

Enterprise marketplace restrictions

For organizations requiring strict control over plugin sources, enterprise administrators can restrict which plugin marketplaces users are allowed to add using the strictKnownMarketplaces setting in managed settings.

When strictKnownMarketplaces is configured in managed settings, the restriction behavior depends on the value:

ValueBehavior
Undefined (default)No restrictions. Users can add any marketplace
Empty array []Complete lockdown. Users cannot add any new marketplaces
List of sourcesUsers can only add marketplaces that match the allowlist exactly

Common configurations

Disable all marketplace additions:

{
  "strictKnownMarketplaces": []
}

Allow specific marketplaces only:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

How restrictions work

Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.

The allowlist uses exact matching. For a marketplace to be allowed, all specified fields must match exactly:

  • For GitHub sources: repo is required, and ref or path must also match if specified in the allowlist
  • For URL sources: the full URL must match exactly

Because strictKnownMarketplaces is set in managed settings, individual users and project configurations cannot override these restrictions.

For complete configuration details including all supported source types and comparison with extraKnownMarketplaces, see the strictKnownMarketplaces reference.

Validation and testing

Test your marketplace before sharing.

Validate your marketplace JSON syntax:

claude plugin validate .

Or from within Claude Code:

/plugin validate .

Add the marketplace for testing:

/plugin marketplace add ./path/to/marketplace

Install a test plugin to verify everything works:

/plugin install test-plugin@marketplace-name

For complete plugin testing workflows, see Test your plugins locally. For technical troubleshooting, see Plugins reference.

Troubleshooting

Marketplace not loading

Symptoms: Can't add marketplace or see plugins from it

Solutions:

  • Verify the marketplace URL is accessible
  • Check that .claude-plugin/marketplace.json exists at the specified path
  • Ensure JSON syntax is valid using claude plugin validate or /plugin validate
  • For private repositories, confirm you have access permissions

Marketplace validation errors

Run claude plugin validate . or /plugin validate . from your marketplace directory to check for issues. Common errors:

ErrorCauseSolution
File not found: .claude-plugin/marketplace.jsonMissing manifestCreate .claude-plugin/marketplace.json with required fields
Invalid JSON syntax: Unexpected token...JSON syntax errorCheck for missing commas, extra commas, or unquoted strings
Duplicate plugin name "x" found in marketplaceTwo plugins share the same nameGive each plugin a unique name value
plugins[0].source: Path traversal not allowedSource path contains ..Use paths relative to marketplace root without ..

Warnings (non-blocking):

  • Marketplace has no plugins defined: add at least one plugin to the plugins array
  • No marketplace description provided: add metadata.description to help users understand your marketplace
  • Plugin "x" uses npm source which is not yet fully implemented: use github or local path sources instead

Plugin installation failures

Symptoms: Marketplace appears but plugin installation fails

Solutions:

  • Verify plugin source URLs are accessible
  • Check that plugin directories contain required files
  • For GitHub sources, ensure repositories are public or you have access
  • Test plugin sources manually by cloning/downloading

Files not found after installation

Symptoms: Plugin installs but references to files fail, especially files outside the plugin directory

Cause: Plugins are copied to a cache directory rather than used in-place. Paths that reference files outside the plugin's directory (such as ../shared-utils) won't work because those files aren't copied.

Solutions: See Plugin caching and file resolution for workarounds including symlinks and directory restructuring.

For additional debugging tools and common issues, see Debugging and development tools.

See also

  • Discover and install prebuilt plugins - Installing plugins from existing marketplaces
  • Plugins - Creating your own plugins
  • Plugins reference - Complete technical specifications and schemas
  • Plugin settings - Plugin configuration options
  • strictKnownMarketplaces reference - Enterprise marketplace restrictions

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt

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.