mirror of
https://github.com/dotneet/claude-code-marketplace.git
synced 2026-09-14 14:18:13 +08:00
add CLAUDE.md and docs
This commit is contained in:
Shinji Yamada
@@ -0,0 +1,609 @@
|
||||
# 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](/en/discover-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](/en/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](#create-the-marketplace-file)).
|
||||
3. **Host the marketplace**: push to GitHub, GitLab, or another git host (see [Host and distribute marketplaces](#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](/en/discover-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` skill for code reviews. You'll create the directory structure, add a skill, 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/skills/review
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create the skill">
|
||||
Create a `SKILL.md` file that defines what the `/review` skill does.
|
||||
|
||||
```markdown my-marketplace/plugins/review-plugin/skills/review/SKILL.md theme={null}
|
||||
---
|
||||
description: Review code for bugs, security, and performance
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
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 skill 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 skill 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](/en/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](/en/plugins-reference#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](#marketplace-schema) below for all available fields.
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"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
|
||||
|
||||
| Field | Type | Description | Example |
|
||||
| :-------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
|
||||
| `name` | string | Marketplace 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"` |
|
||||
| `owner` | object | Marketplace maintainer information ([see fields below](#owner-fields)) | |
|
||||
| `plugins` | array | List of available plugins | See 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
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| :------ | :----- | :------- | :------------------------------- |
|
||||
| `name` | string | Yes | Name of the maintainer or team |
|
||||
| `email` | string | No | Contact email for the maintainer |
|
||||
|
||||
### Optional metadata
|
||||
|
||||
| Field | Type | Description |
|
||||
| :--------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `metadata.description` | string | Brief marketplace description |
|
||||
| `metadata.version` | string | Marketplace version |
|
||||
| `metadata.pluginRoot` | string | Base 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](/en/plugins-reference#plugin-manifest-schema) (like `description`, `version`, `author`, `commands`, `hooks`, etc.), plus these marketplace-specific fields: `source`, `category`, `tags`, and `strict`.
|
||||
|
||||
### Required fields
|
||||
|
||||
| Field | Type | Description |
|
||||
| :------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | string | Plugin identifier (kebab-case, no spaces). This is public-facing: users see it when installing (for example, `/plugin install my-plugin@marketplace`). |
|
||||
| `source` | string\|object | Where to fetch the plugin from (see [Plugin sources](#plugin-sources) below) |
|
||||
|
||||
### Optional plugin fields
|
||||
|
||||
**Standard metadata fields:**
|
||||
|
||||
| Field | Type | Description |
|
||||
| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `description` | string | Brief plugin description |
|
||||
| `version` | string | Plugin version |
|
||||
| `author` | object | Plugin author information (`name` required, `email` optional) |
|
||||
| `homepage` | string | Plugin homepage or documentation URL |
|
||||
| `repository` | string | Source code repository URL |
|
||||
| `license` | string | SPDX license identifier (for example, MIT, Apache-2.0) |
|
||||
| `keywords` | array | Tags for plugin discovery and categorization |
|
||||
| `category` | string | Plugin category for organization |
|
||||
| `tags` | array | Tags for searchability |
|
||||
| `strict` | boolean | Controls 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:**
|
||||
|
||||
| Field | Type | Description |
|
||||
| :----------- | :------------- | :----------------------------------------------- |
|
||||
| `commands` | string\|array | Custom paths to command files or directories |
|
||||
| `agents` | string\|array | Custom paths to agent files |
|
||||
| `hooks` | string\|object | Custom hooks configuration or path to hooks file |
|
||||
| `mcpServers` | string\|object | MCP server configurations or path to MCP config |
|
||||
| `lspServers` | string\|object | LSP server configurations or path to LSP config |
|
||||
|
||||
## Plugin sources
|
||||
|
||||
### Relative paths
|
||||
|
||||
For plugins in the same repository:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "./plugins/my-plugin"
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Relative paths only work when users add your marketplace via Git (GitHub, GitLab, or git URL). If users add your marketplace via a direct URL to the `marketplace.json` file, relative paths will not resolve correctly. For URL-based distribution, use GitHub, npm, or git URL sources instead. See [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.
|
||||
</Note>
|
||||
|
||||
### GitHub repositories
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"name": "github-plugin",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "owner/plugin-repo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can pin to a specific branch, tag, or commit:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"name": "github-plugin",
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "owner/plugin-repo",
|
||||
"ref": "v2.0.0",
|
||||
"sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
| :----- | :----- | :-------------------------------------------------------------------- |
|
||||
| `repo` | string | Required. GitHub repository in `owner/repo` format |
|
||||
| `ref` | string | Optional. Git branch or tag (defaults to repository default branch) |
|
||||
| `sha` | string | Optional. Full 40-character git commit SHA to pin to an exact version |
|
||||
|
||||
### Git repositories
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"name": "git-plugin",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://gitlab.com/team/plugin.git"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can pin to a specific branch, tag, or commit:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"name": "git-plugin",
|
||||
"source": {
|
||||
"source": "url",
|
||||
"url": "https://gitlab.com/team/plugin.git",
|
||||
"ref": "main",
|
||||
"sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
| :---- | :----- | :-------------------------------------------------------------------- |
|
||||
| `url` | string | Required. Full git repository URL (must end with `.git`) |
|
||||
| `ref` | string | Optional. Git branch or tag (defaults to repository default branch) |
|
||||
| `sha` | string | Optional. Full 40-character git commit SHA to pin to an exact version |
|
||||
|
||||
### 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:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"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:
|
||||
|
||||
```shell theme={null}
|
||||
/plugin marketplace add https://gitlab.com/company/plugins.git
|
||||
```
|
||||
|
||||
### Private repositories
|
||||
|
||||
Claude Code supports installing plugins from private repositories. Set the appropriate authentication token in your environment, and Claude Code will use it when authentication is required.
|
||||
|
||||
| Provider | Environment variables | Notes |
|
||||
| :-------- | :--------------------------- | :---------------------------------------- |
|
||||
| GitHub | `GITHUB_TOKEN` or `GH_TOKEN` | Personal access token or GitHub App token |
|
||||
| GitLab | `GITLAB_TOKEN` or `GL_TOKEN` | Personal access token or project token |
|
||||
| Bitbucket | `BITBUCKET_TOKEN` | App password or repository access token |
|
||||
|
||||
Set the token in your shell configuration (for example, `.bashrc`, `.zshrc`) or pass it when running Claude Code:
|
||||
|
||||
```bash theme={null}
|
||||
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
Authentication tokens are only used when a repository requires authentication. Public repositories work without any tokens configured, even if tokens are present in your environment.
|
||||
|
||||
<Note>
|
||||
For CI/CD environments, configure the token as a secret environment variable. GitHub Actions automatically provides `GITHUB_TOKEN` for repositories in the same organization.
|
||||
</Note>
|
||||
|
||||
### Test locally before distribution
|
||||
|
||||
Test your marketplace locally before sharing:
|
||||
|
||||
```shell theme={null}
|
||||
/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](/en/discover-plugins#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`:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"extraKnownMarketplaces": {
|
||||
"company-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "your-org/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also specify which plugins should be enabled by default:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"code-formatter@company-tools": true,
|
||||
"deployment-tools@company-tools": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For full configuration options, see [Plugin settings](/en/settings#plugin-settings).
|
||||
|
||||
### Managed marketplace restrictions
|
||||
|
||||
For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) setting in managed settings.
|
||||
|
||||
When `strictKnownMarketplaces` is configured in managed settings, the restriction behavior depends on the value:
|
||||
|
||||
| Value | Behavior |
|
||||
| ------------------- | ---------------------------------------------------------------- |
|
||||
| Undefined (default) | No restrictions. Users can add any marketplace |
|
||||
| Empty array `[]` | Complete lockdown. Users cannot add any new marketplaces |
|
||||
| List of sources | Users can only add marketplaces that match the allowlist exactly |
|
||||
|
||||
#### Common configurations
|
||||
|
||||
Disable all marketplace additions:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"strictKnownMarketplaces": []
|
||||
}
|
||||
```
|
||||
|
||||
Allow specific marketplaces only:
|
||||
|
||||
```json theme={null}
|
||||
{
|
||||
"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](/en/settings#settings-files), 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](/en/settings#strictknownmarketplaces).
|
||||
|
||||
## Validation and testing
|
||||
|
||||
Test your marketplace before sharing.
|
||||
|
||||
Validate your marketplace JSON syntax:
|
||||
|
||||
```bash theme={null}
|
||||
claude plugin validate .
|
||||
```
|
||||
|
||||
Or from within Claude Code:
|
||||
|
||||
```shell theme={null}
|
||||
/plugin validate .
|
||||
```
|
||||
|
||||
Add the marketplace for testing:
|
||||
|
||||
```shell theme={null}
|
||||
/plugin marketplace add ./path/to/marketplace
|
||||
```
|
||||
|
||||
Install a test plugin to verify everything works:
|
||||
|
||||
```shell theme={null}
|
||||
/plugin install test-plugin@marketplace-name
|
||||
```
|
||||
|
||||
For complete plugin testing workflows, see [Test your plugins locally](/en/plugins#test-your-plugins-locally). For technical troubleshooting, see [Plugins reference](/en/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:
|
||||
|
||||
| Error | Cause | Solution |
|
||||
| :------------------------------------------------ | :------------------------------ | :------------------------------------------------------------ |
|
||||
| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create `.claude-plugin/marketplace.json` with required fields |
|
||||
| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Check for missing commas, extra commas, or unquoted strings |
|
||||
| `Duplicate plugin name "x" found in marketplace` | Two plugins share the same name | Give each plugin a unique `name` value |
|
||||
| `plugins[0].source: Path traversal not allowed` | Source 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
|
||||
|
||||
### Private repository authentication fails
|
||||
|
||||
**Symptoms**: Authentication errors when installing plugins from private repositories, even with tokens configured
|
||||
|
||||
**Solutions**:
|
||||
|
||||
* Verify your token is set in the current shell session: `echo $GITHUB_TOKEN`
|
||||
* Check that the token has the required permissions (read access to the repository)
|
||||
* For GitHub, ensure the token has the `repo` scope for private repositories
|
||||
* For GitLab, ensure the token has at least `read_repository` scope
|
||||
* Verify the token hasn't expired
|
||||
* If using multiple git providers, ensure you've set the token for the correct provider
|
||||
|
||||
### Plugins with relative paths fail in URL-based marketplaces
|
||||
|
||||
**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.
|
||||
|
||||
**Cause**: URL-based marketplaces only download the `marketplace.json` file itself. They do not download plugin files from the server. Relative paths in the marketplace entry reference files on the remote server that were not downloaded.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
* **Use external sources**: Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths:
|
||||
```json theme={null}
|
||||
{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
|
||||
```
|
||||
* **Use a Git-based marketplace**: Host your marketplace in a Git repository and add it with the git URL. Git-based marketplaces clone the entire repository, making relative paths work correctly.
|
||||
|
||||
### 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](/en/plugins-reference#plugin-caching-and-file-resolution) for workarounds including symlinks and directory restructuring.
|
||||
|
||||
For additional debugging tools and common issues, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).
|
||||
|
||||
## See also
|
||||
|
||||
* [Discover and install prebuilt plugins](/en/discover-plugins) - Installing plugins from existing marketplaces
|
||||
* [Plugins](/en/plugins) - Creating your own plugins
|
||||
* [Plugins reference](/en/plugins-reference) - Complete technical specifications and schemas
|
||||
* [Plugin settings](/en/settings#plugin-settings) - Plugin configuration options
|
||||
* [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces) - Managed marketplace restrictions
|
||||
|
||||
|
||||
---
|
||||
|
||||
> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt
|
||||
@@ -0,0 +1,645 @@
|
||||
# Extend Claude with skills
|
||||
|
||||
> Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom slash commands.
|
||||
|
||||
Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.
|
||||
|
||||
<Note>
|
||||
For built-in commands like `/help` and `/compact`, see [interactive mode](/en/interactive-mode#built-in-commands).
|
||||
|
||||
**Custom slash commands have been merged into skills.** A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.
|
||||
</Note>
|
||||
|
||||
Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context).
|
||||
|
||||
## Getting started
|
||||
|
||||
### Create your first skill
|
||||
|
||||
This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. Since it uses default frontmatter, Claude can load it automatically when you ask how something works, or you can invoke it directly with `/explain-code`.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the skill directory">
|
||||
Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.
|
||||
|
||||
```bash theme={null}
|
||||
mkdir -p ~/.claude/skills/explain-code
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Write SKILL.md">
|
||||
Every skill needs a `SKILL.md` file with two parts: YAML frontmatter (between `---` markers) that tells Claude when to use the skill, and markdown content with instructions Claude follows when the skill is invoked. The `name` field becomes the `/slash-command`, and the `description` helps Claude decide when to load it automatically.
|
||||
|
||||
Create `~/.claude/skills/explain-code/SKILL.md`:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: explain-code
|
||||
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
|
||||
---
|
||||
|
||||
When explaining code, always include:
|
||||
|
||||
1. **Start with an analogy**: Compare the code to something from everyday life
|
||||
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
|
||||
3. **Walk through the code**: Explain step-by-step what happens
|
||||
4. **Highlight a gotcha**: What's a common mistake or misconception?
|
||||
|
||||
Keep explanations conversational. For complex concepts, use multiple analogies.
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Test the skill">
|
||||
You can test it two ways:
|
||||
|
||||
**Let Claude invoke it automatically** by asking something that matches the description:
|
||||
|
||||
```
|
||||
How does this code work?
|
||||
```
|
||||
|
||||
**Or invoke it directly** with the skill name:
|
||||
|
||||
```
|
||||
/explain-code src/auth/login.ts
|
||||
```
|
||||
|
||||
Either way, Claude should include an analogy and ASCII diagram in its explanation.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Where skills live
|
||||
|
||||
Where you store a skill determines who can use it:
|
||||
|
||||
| Location | Path | Applies to |
|
||||
| :--------- | :----------------------------------------------- | :----------------------------- |
|
||||
| Enterprise | See [managed settings](/en/iam#managed-settings) | All users in your organization |
|
||||
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects |
|
||||
| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |
|
||||
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |
|
||||
|
||||
When skills share the same name across levels, higher-priority locations win: enterprise > personal > project. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels. If you have files in `.claude/commands/`, those work the same way, but if a skill and a command share the same name, the skill takes precedence.
|
||||
|
||||
#### Automatic discovery from nested directories
|
||||
|
||||
When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.
|
||||
|
||||
Each skill is a directory with `SKILL.md` as the entrypoint:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Main instructions (required)
|
||||
├── template.md # Template for Claude to fill in
|
||||
├── examples/
|
||||
│ └── sample.md # Example output showing expected format
|
||||
└── scripts/
|
||||
└── validate.sh # Script Claude can execute
|
||||
```
|
||||
|
||||
The `SKILL.md` contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation. Reference these files from your `SKILL.md` so Claude knows what they contain and when to load them. See [Add supporting files](#add-supporting-files) for more details.
|
||||
|
||||
<Note>
|
||||
Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files.
|
||||
</Note>
|
||||
|
||||
## Configure skills
|
||||
|
||||
Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows.
|
||||
|
||||
### Types of skill content
|
||||
|
||||
Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include:
|
||||
|
||||
**Reference content** adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context.
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: api-conventions
|
||||
description: API design patterns for this codebase
|
||||
---
|
||||
|
||||
When writing API endpoints:
|
||||
- Use RESTful naming conventions
|
||||
- Return consistent error formats
|
||||
- Include request validation
|
||||
```
|
||||
|
||||
**Task content** gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation. These are often actions you want to invoke directly with `/skill-name` rather than letting Claude decide when to run them. Add `disable-model-invocation: true` to prevent Claude from triggering it automatically.
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: deploy
|
||||
description: Deploy the application to production
|
||||
context: fork
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Deploy the application:
|
||||
1. Run the test suite
|
||||
2. Build the application
|
||||
3. Push to the deployment target
|
||||
```
|
||||
|
||||
Your `SKILL.md` can contain anything, but thinking through how you want the skill invoked (by you, by Claude, or both) and where you want it to run (inline or in a subagent) helps guide what to include. For complex skills, you can also [add supporting files](#add-supporting-files) to keep the main skill focused.
|
||||
|
||||
### Frontmatter reference
|
||||
|
||||
Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between `---` markers at the top of your `SKILL.md` file:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: my-skill
|
||||
description: What this skill does
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Read, Grep
|
||||
---
|
||||
|
||||
Your skill instructions here...
|
||||
```
|
||||
|
||||
All fields are optional. Only `description` is recommended so Claude knows when to use the skill.
|
||||
|
||||
| Field | Required | Description |
|
||||
| :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |
|
||||
| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |
|
||||
| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |
|
||||
| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |
|
||||
| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. |
|
||||
| `model` | No | Model to use when this skill is active. |
|
||||
| `context` | No | Set to `fork` to run in a forked subagent context. |
|
||||
| `agent` | No | Which subagent type to use when `context: fork` is set. |
|
||||
| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks](/en/hooks) for configuration format. |
|
||||
|
||||
#### Available string substitutions
|
||||
|
||||
Skills support string substitution for dynamic values in the skill content:
|
||||
|
||||
| Variable | Description |
|
||||
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |
|
||||
| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |
|
||||
|
||||
**Example using substitutions:**
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: session-logger
|
||||
description: Log activity for this session
|
||||
---
|
||||
|
||||
Log the following to logs/${CLAUDE_SESSION_ID}.log:
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
### Add supporting files
|
||||
|
||||
Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs.
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md (required - overview and navigation)
|
||||
├── reference.md (detailed API docs - loaded when needed)
|
||||
├── examples.md (usage examples - loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py (utility script - executed, not loaded)
|
||||
```
|
||||
|
||||
Reference supporting files from `SKILL.md` so Claude knows what each file contains and when to load it:
|
||||
|
||||
```markdown theme={null}
|
||||
## Additional resources
|
||||
|
||||
- For complete API details, see [reference.md](reference.md)
|
||||
- For usage examples, see [examples.md](examples.md)
|
||||
```
|
||||
|
||||
<Tip>Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files.</Tip>
|
||||
|
||||
### Control who invokes a skill
|
||||
|
||||
By default, both you and Claude can invoke any skill. You can type `/skill-name` to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:
|
||||
|
||||
* **`disable-model-invocation: true`**: Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing, like `/commit`, `/deploy`, or `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
|
||||
|
||||
* **`user-invocable: false`**: Only Claude can invoke the skill. Use this for background knowledge that isn't actionable as a command. A `legacy-system-context` skill explains how an old system works. Claude should know this when relevant, but `/legacy-system-context` isn't a meaningful action for users to take.
|
||||
|
||||
This example creates a deploy skill that only you can trigger. The `disable-model-invocation: true` field prevents Claude from running it automatically:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: deploy
|
||||
description: Deploy the application to production
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Deploy $ARGUMENTS to production:
|
||||
|
||||
1. Run the test suite
|
||||
2. Build the application
|
||||
3. Push to the deployment target
|
||||
4. Verify the deployment succeeded
|
||||
```
|
||||
|
||||
Here's how the two fields affect invocation and context loading:
|
||||
|
||||
| Frontmatter | You can invoke | Claude can invoke | When loaded into context |
|
||||
| :------------------------------- | :------------- | :---------------- | :----------------------------------------------------------- |
|
||||
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |
|
||||
|
||||
<Note>
|
||||
In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](/en/sub-agents#preload-skills-into-subagents) work differently: the full skill content is injected at startup.
|
||||
</Note>
|
||||
|
||||
### Restrict tool access
|
||||
|
||||
Use the `allowed-tools` field to limit which tools Claude can use when a skill is active. This skill creates a read-only mode where Claude can explore files but not modify them:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: safe-reader
|
||||
description: Read files without making changes
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
### Pass arguments to skills
|
||||
|
||||
Both you and Claude can pass arguments when invoking a skill. Arguments are available via the `$ARGUMENTS` placeholder.
|
||||
|
||||
This skill fixes a GitHub issue by number. The `$ARGUMENTS` placeholder gets replaced with whatever follows the skill name:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: fix-issue
|
||||
description: Fix a GitHub issue
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Fix GitHub issue $ARGUMENTS following our coding standards.
|
||||
|
||||
1. Read the issue description
|
||||
2. Understand the requirements
|
||||
3. Implement the fix
|
||||
4. Write tests
|
||||
5. Create a commit
|
||||
```
|
||||
|
||||
When you run `/fix-issue 123`, Claude receives "Fix GitHub issue 123 following our coding standards..."
|
||||
|
||||
If you invoke a skill with arguments but the skill doesn't include `$ARGUMENTS`, Claude Code appends `ARGUMENTS: <your input>` to the end of the skill content so Claude still sees what you typed.
|
||||
|
||||
## Advanced patterns
|
||||
|
||||
### Inject dynamic context
|
||||
|
||||
The `!`command\`\` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.
|
||||
|
||||
This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `!`gh pr diff\`\` and other commands run first, and their output gets inserted into the prompt:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: pr-summary
|
||||
description: Summarize changes in a pull request
|
||||
context: fork
|
||||
agent: Explore
|
||||
allowed-tools: Bash(gh:*)
|
||||
---
|
||||
|
||||
## Pull request context
|
||||
- PR diff: !`gh pr diff`
|
||||
- PR comments: !`gh pr view --comments`
|
||||
- Changed files: !`gh pr diff --name-only`
|
||||
|
||||
## Your task
|
||||
Summarize this pull request...
|
||||
```
|
||||
|
||||
When this skill runs:
|
||||
|
||||
1. Each `!`command\`\` executes immediately (before Claude sees anything)
|
||||
2. The output replaces the placeholder in the skill content
|
||||
3. Claude receives the fully-rendered prompt with actual PR data
|
||||
|
||||
This is preprocessing, not something Claude executes. Claude only sees the final result.
|
||||
|
||||
<Tip>
|
||||
To enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) in a skill, include the word "ultrathink" anywhere in your skill content.
|
||||
</Tip>
|
||||
|
||||
### Run skills in a subagent
|
||||
|
||||
Add `context: fork` to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history.
|
||||
|
||||
<Warning>
|
||||
`context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.
|
||||
</Warning>
|
||||
|
||||
Skills and [subagents](/en/sub-agents) work together in two directions:
|
||||
|
||||
| Approach | System prompt | Task | Also loads |
|
||||
| :--------------------------- | :---------------------------------------- | :-------------------------- | :--------------------------- |
|
||||
| Skill with `context: fork` | From agent type (`Explore`, `Plan`, etc.) | SKILL.md content | CLAUDE.md |
|
||||
| Subagent with `skills` field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md |
|
||||
|
||||
With `context: fork`, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see [Subagents](/en/sub-agents#preload-skills-into-subagents).
|
||||
|
||||
#### Example: Research skill using Explore agent
|
||||
|
||||
This skill runs research in a forked Explore agent. The skill content becomes the task, and the agent provides read-only tools optimized for codebase exploration:
|
||||
|
||||
```yaml theme={null}
|
||||
---
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
Research $ARGUMENTS thoroughly:
|
||||
|
||||
1. Find relevant files using Glob and Grep
|
||||
2. Read and analyze the code
|
||||
3. Summarize findings with specific file references
|
||||
```
|
||||
|
||||
When this skill runs:
|
||||
|
||||
1. A new isolated context is created
|
||||
2. The subagent receives the skill content as its prompt ("Research \$ARGUMENTS thoroughly...")
|
||||
3. The `agent` field determines the execution environment (model, tools, and permissions)
|
||||
4. Results are summarized and returned to your main conversation
|
||||
|
||||
The `agent` field specifies which subagent configuration to use. Options include built-in agents (`Explore`, `Plan`, `general-purpose`) or any custom subagent from `.claude/agents/`. If omitted, uses `general-purpose`.
|
||||
|
||||
### Restrict Claude's skill access
|
||||
|
||||
By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Built-in commands like `/compact` and `/init` are not available through the Skill tool.
|
||||
|
||||
Three ways to control which skills Claude can invoke:
|
||||
|
||||
**Disable all skills** by denying the Skill tool in `/permissions`:
|
||||
|
||||
```
|
||||
# Add to deny rules:
|
||||
Skill
|
||||
```
|
||||
|
||||
**Allow or deny specific skills** using [permission rules](/en/iam):
|
||||
|
||||
```
|
||||
# Allow only specific skills
|
||||
Skill(commit)
|
||||
Skill(review-pr:*)
|
||||
|
||||
# Deny specific skills
|
||||
Skill(deploy:*)
|
||||
```
|
||||
|
||||
Permission syntax: `Skill(name)` for exact match, `Skill(name:*)` for prefix match with any arguments.
|
||||
|
||||
**Hide individual skills** by adding `disable-model-invocation: true` to their frontmatter. This removes the skill from Claude's context entirely.
|
||||
|
||||
<Note>
|
||||
The `user-invocable` field only controls menu visibility, not Skill tool access. Use `disable-model-invocation: true` to block programmatic invocation.
|
||||
</Note>
|
||||
|
||||
## Share skills
|
||||
|
||||
Skills can be distributed at different scopes depending on your audience:
|
||||
|
||||
* **Project skills**: Commit `.claude/skills/` to version control
|
||||
* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)
|
||||
* **Managed**: Deploy organization-wide through [managed settings](/en/iam#managed-settings)
|
||||
|
||||
### Generate visual output
|
||||
|
||||
Skills can bundle and run scripts in any language, giving Claude capabilities beyond what's possible in a single prompt. One powerful pattern is generating visual output: interactive HTML files that open in your browser for exploring data, debugging, or creating reports.
|
||||
|
||||
This example creates a codebase explorer: an interactive tree view where you can expand and collapse directories, see file sizes at a glance, and identify file types by color.
|
||||
|
||||
Create the Skill directory:
|
||||
|
||||
```bash theme={null}
|
||||
mkdir -p ~/.claude/skills/codebase-visualizer/scripts
|
||||
```
|
||||
|
||||
Create `~/.claude/skills/codebase-visualizer/SKILL.md`. The description tells Claude when to activate this Skill, and the instructions tell Claude to run the bundled script:
|
||||
|
||||
````yaml theme={null}
|
||||
---
|
||||
name: codebase-visualizer
|
||||
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
|
||||
allowed-tools: Bash(python:*)
|
||||
---
|
||||
|
||||
# Codebase Visualizer
|
||||
|
||||
Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.
|
||||
|
||||
## Usage
|
||||
|
||||
Run the visualization script from your project root:
|
||||
|
||||
```bash
|
||||
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
|
||||
```
|
||||
|
||||
This creates `codebase-map.html` in the current directory and opens it in your default browser.
|
||||
|
||||
## What the visualization shows
|
||||
|
||||
- **Collapsible directories**: Click folders to expand/collapse
|
||||
- **File sizes**: Displayed next to each file
|
||||
- **Colors**: Different colors for different file types
|
||||
- **Directory totals**: Shows aggregate size of each folder
|
||||
````
|
||||
|
||||
Create `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with:
|
||||
|
||||
* A **summary sidebar** showing file count, directory count, total size, and number of file types
|
||||
* A **bar chart** breaking down the codebase by file type (top 8 by size)
|
||||
* A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators
|
||||
|
||||
The script requires Python but uses only built-in libraries, so there are no packages to install:
|
||||
|
||||
```python expandable theme={null}
|
||||
#!/usr/bin/env python3
|
||||
"""Generate an interactive collapsible tree visualization of a codebase."""
|
||||
|
||||
import json
|
||||
import sys
|
||||
import webbrowser
|
||||
from pathlib import Path
|
||||
from collections import Counter
|
||||
|
||||
IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}
|
||||
|
||||
def scan(path: Path, stats: dict) -> dict:
|
||||
result = {"name": path.name, "children": [], "size": 0}
|
||||
try:
|
||||
for item in sorted(path.iterdir()):
|
||||
if item.name in IGNORE or item.name.startswith('.'):
|
||||
continue
|
||||
if item.is_file():
|
||||
size = item.stat().st_size
|
||||
ext = item.suffix.lower() or '(no ext)'
|
||||
result["children"].append({"name": item.name, "size": size, "ext": ext})
|
||||
result["size"] += size
|
||||
stats["files"] += 1
|
||||
stats["extensions"][ext] += 1
|
||||
stats["ext_sizes"][ext] += size
|
||||
elif item.is_dir():
|
||||
stats["dirs"] += 1
|
||||
child = scan(item, stats)
|
||||
if child["children"]:
|
||||
result["children"].append(child)
|
||||
result["size"] += child["size"]
|
||||
except PermissionError:
|
||||
pass
|
||||
return result
|
||||
|
||||
def generate_html(data: dict, stats: dict, output: Path) -> None:
|
||||
ext_sizes = stats["ext_sizes"]
|
||||
total_size = sum(ext_sizes.values()) or 1
|
||||
sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
|
||||
colors = {
|
||||
'.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
|
||||
'.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
|
||||
'.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
|
||||
'.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
|
||||
}
|
||||
lang_bars = "".join(
|
||||
f'<div class="bar-row"><span class="bar-label">{ext}</span>'
|
||||
f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
|
||||
f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
|
||||
for ext, size in sorted_exts
|
||||
)
|
||||
def fmt(b):
|
||||
if b < 1024: return f"{b} B"
|
||||
if b < 1048576: return f"{b/1024:.1f} KB"
|
||||
return f"{b/1048576:.1f} MB"
|
||||
|
||||
html = f'''<!DOCTYPE html>
|
||||
<html><head>
|
||||
<meta charset="utf-8"><title>Codebase Explorer</title>
|
||||
<style>
|
||||
body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
|
||||
.container {{ display: flex; height: 100vh; }}
|
||||
.sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
|
||||
.main {{ flex: 1; padding: 20px; overflow-y: auto; }}
|
||||
h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
|
||||
h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
|
||||
.stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
|
||||
.stat-value {{ font-weight: bold; }}
|
||||
.bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
|
||||
.bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
|
||||
.bar {{ height: 18px; border-radius: 3px; }}
|
||||
.bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
|
||||
.tree {{ list-style: none; padding-left: 20px; }}
|
||||
details {{ cursor: pointer; }}
|
||||
summary {{ padding: 4px 8px; border-radius: 4px; }}
|
||||
summary:hover {{ background: #2d2d44; }}
|
||||
.folder {{ color: #ffd700; }}
|
||||
.file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
|
||||
.file:hover {{ background: #2d2d44; }}
|
||||
.size {{ color: #888; margin-left: auto; font-size: 12px; }}
|
||||
.dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
|
||||
</style>
|
||||
</head><body>
|
||||
<div class="container">
|
||||
<div class="sidebar">
|
||||
<h1>📊 Summary</h1>
|
||||
<div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
|
||||
<div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
|
||||
<div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
|
||||
<div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
|
||||
<h2>By file type</h2>
|
||||
{lang_bars}
|
||||
</div>
|
||||
<div class="main">
|
||||
<h1>📁 {data["name"]}</h1>
|
||||
<ul class="tree" id="root"></ul>
|
||||
</div>
|
||||
</div>
|
||||
<script>
|
||||
const data = {json.dumps(data)};
|
||||
const colors = {json.dumps(colors)};
|
||||
function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}
|
||||
function render(node, parent) {{
|
||||
if (node.children) {{
|
||||
const det = document.createElement('details');
|
||||
det.open = parent === document.getElementById('root');
|
||||
det.innerHTML = `<summary><span class="folder">📁 ${{node.name}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;
|
||||
const ul = document.createElement('ul'); ul.className = 'tree';
|
||||
node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));
|
||||
node.children.forEach(c => render(c, ul));
|
||||
det.appendChild(ul);
|
||||
const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);
|
||||
}} else {{
|
||||
const li = document.createElement('li'); li.className = 'file';
|
||||
li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{node.name}}<span class="size">${{fmt(node.size)}}</span>`;
|
||||
parent.appendChild(li);
|
||||
}}
|
||||
}}
|
||||
data.children.forEach(c => render(c, document.getElementById('root')));
|
||||
</script>
|
||||
</body></html>'''
|
||||
output.write_text(html)
|
||||
|
||||
if __name__ == '__main__':
|
||||
target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
|
||||
stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
|
||||
data = scan(target, stats)
|
||||
out = Path('codebase-map.html')
|
||||
generate_html(data, stats, out)
|
||||
print(f'Generated {out.absolute()}')
|
||||
webbrowser.open(f'file://{out.absolute()}')
|
||||
```
|
||||
|
||||
To test, open Claude Code in any project and ask "Visualize this codebase." Claude runs the script, generates `codebase-map.html`, and opens it in your browser.
|
||||
|
||||
This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the heavy lifting while Claude handles orchestration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Skill not triggering
|
||||
|
||||
If Claude doesn't use your skill when expected:
|
||||
|
||||
1. Check the description includes keywords users would naturally say
|
||||
2. Verify the skill appears in `What skills are available?`
|
||||
3. Try rephrasing your request to match the description more closely
|
||||
4. Invoke it directly with `/skill-name` if the skill is user-invocable
|
||||
|
||||
### Skill triggers too often
|
||||
|
||||
If Claude uses your skill when you don't want it:
|
||||
|
||||
1. Make the description more specific
|
||||
2. Add `disable-model-invocation: true` if you only want manual invocation
|
||||
|
||||
### Claude doesn't see all my skills
|
||||
|
||||
Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget (default 15,000 characters). Run `/context` to check for a warning about excluded skills.
|
||||
|
||||
To increase the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.
|
||||
|
||||
## Related resources
|
||||
|
||||
* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents
|
||||
* **[Plugins](/en/plugins)**: package and distribute skills with other extensions
|
||||
* **[Hooks](/en/hooks)**: automate workflows around tool events
|
||||
* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context
|
||||
* **[Interactive mode](/en/interactive-mode#built-in-commands)**: built-in commands and shortcuts
|
||||
* **[Permissions](/en/iam)**: control tool and skill access
|
||||
|
||||
|
||||
---
|
||||
|
||||
> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt
|
||||
@@ -3,6 +3,7 @@
|
||||
|
||||
# Claude Code local settings
|
||||
.claude/settings.local.json
|
||||
.claude/plans/
|
||||
|
||||
# Editor
|
||||
.idea/
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Repository Overview
|
||||
|
||||
Claude Code plugin marketplace containing multiple plugins with skills for code review, agent delegation, research, and Google services integration. Plugins are distributed via the `/plugin marketplace add dotneet/claude-code-marketplace` command.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
.claude-plugin/marketplace.json # Marketplace catalog (root)
|
||||
<plugin-name>/
|
||||
.claude-plugin/plugin.json # Plugin manifest
|
||||
skills/<skill-name>/
|
||||
SKILL.md # Skill definition (frontmatter + instructions)
|
||||
references/ # Reference docs for the skill
|
||||
```
|
||||
|
||||
## Plugins
|
||||
|
||||
| Plugin | Skills |
|
||||
|--------|--------|
|
||||
| review-tool | typescript-react-reviewer, code-modularization-evaluator |
|
||||
| agent-call | call-claude, call-codex, call-cursor-agent |
|
||||
| agent-session | suggest-agent-rules |
|
||||
| research | perplexity-search (requires `PERPLEXITY_API_KEY`), context7 (requires `CONTEXT7_API_KEY`) |
|
||||
| google | google-calendar |
|
||||
|
||||
## Reference Documentation
|
||||
|
||||
Official Claude Code documentation for plugins and skills is available in `.claude/docs/`:
|
||||
- `skills.md` - Skill creation guide
|
||||
- `plugin-marketplaces.md` - Marketplace creation and distribution guide
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Validate marketplace and plugin structure
|
||||
/plugin validate .
|
||||
|
||||
# Test locally
|
||||
/plugin marketplace add ./
|
||||
/plugin install <plugin-name>@dotneet-marketplace
|
||||
```
|
||||
|
||||
## Creating New Skills
|
||||
|
||||
1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter:
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: "Trigger description for the skill"
|
||||
---
|
||||
```
|
||||
2. Add detailed instructions and reference docs in `references/` directory
|
||||
3. Update plugin.json if needed
|
||||
|
||||
## Creating New Plugins
|
||||
|
||||
1. Create `<plugin-name>/.claude-plugin/plugin.json`:
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"description": "Plugin description",
|
||||
"version": "1.0.0",
|
||||
"author": { "name": "Author Name" }
|
||||
}
|
||||
```
|
||||
2. Add skills under `<plugin-name>/skills/`
|
||||
3. Register in `.claude-plugin/marketplace.json` plugins array
|
||||
Reference in New Issue
Block a user