Skip to main content
The Skills CLI supports skill discovery from Claude Code plugin manifests, enabling compatibility with the Claude Code plugin marketplace ecosystem.

​
Overview

Plugin manifests allow you to:
  • Declare skills explicitly instead of relying on directory conventions
  • Group multiple skills under a named plugin
  • Define multi-plugin repositories (marketplace catalogs)
  • Maintain compatibility with Claude Code’s plugin system
Plugin manifests are optional. The CLI will still discover skills in standard locations even without manifests.

​
Supported Manifest Files

The CLI looks for these files in a repository:

marketplace.json

Multi-plugin catalog
Location: .claude-plugin/marketplace.json

plugin.json

Single plugin
Location: .claude-plugin/plugin.json

​
Marketplace Manifest

A marketplace manifest defines multiple plugins in a single repository.

​
File Location

.claude-plugin/marketplace.json

​
Schema

{
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "document-skills",
      "source": "./document-tools",
      "skills": [
        "./skills/markdown-formatter",
        "./skills/doc-generator"
      ]
    },
    {
      "name": "web-skills",
      "source": "./web-tools",
      "skills": [
        "./skills/react-best-practices"
      ]
    }
  ]
}

​
Fields

​
metadata
object
Global metadata for the marketplace
​
plugins
array
required
Array of plugin definitions

​
Path Resolution

Paths are resolved in this order:
  1. Start with repository root
  2. Apply metadata.pluginRoot if present
  3. Apply plugin.source if present
  4. Apply each skill path from plugin.skills
// Given this manifest:
{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    {
      "source": "./document-tools",
      "skills": ["./skills/formatter"]
    }
  ]
}

// Skill path resolves to:
// {repo_root}/plugins/document-tools/skills/formatter/SKILL.md

​
Plugin Manifest

A plugin manifest defines a single plugin at the repository root.

​
File Location

.claude-plugin/plugin.json

​
Schema

{
  "name": "my-plugin",
  "skills": [
    "./skills/react-best-practices",
    "./skills/typescript-guide"
  ]
}

​
Fields

​
name
string
Plugin name for grouping skills
​
skills
string[]
Array of skill paths relative to the repository root. Each path must start with ./

​
Path Resolution

Paths are resolved relative to the repository root: 
// Given this manifest:
{
  "name": "my-plugin",
  "skills": ["./skills/formatter"]
}

// Skill path resolves to:
// {repo_root}/skills/formatter/SKILL.md

​
Security: Path Validation

All paths in plugin manifests are validated to prevent path traversal attacks.

​
Validation Rules

1

Relative path check

All paths must start with ./ per the Claude Code convention
2

Containment check

Resolved paths must be contained within the repository root (no .. segments allowed)
3

Normalization

Paths are normalized before checking containment

​
Invalid Paths

{
  "skills": [
    "../../../etc/passwd",     // ❌ Path traversal
    "/absolute/path",           // ❌ Absolute path
    "relative/path",            // ❌ Missing ./
    "./skills/../../../etc"    // ❌ Escapes repo root
  ]
}

​
How Discovery Works

When you run skills add <source>, the CLI searches for skills in this order:
1

Check for manifests

Look for .claude-plugin/marketplace.json or .claude-plugin/plugin.json
2

Extract declared skills

If manifests exist, add their skill paths to the search list
3

Add conventional directories

Always search standard locations like skills/, .agents/skills/, etc.
4

Discover SKILL.md files

Find all SKILL.md files in the search directories
5

Deduplicate

Remove duplicate skills based on normalized name

​
Discovery Flow

​
Plugin Grouping

Skills discovered from manifests can be grouped by plugin name.

​
In Lock Files

When a skill is installed from a manifest with a name field, the plugin name is stored: 
{
  "skills": {
    "markdown-formatter": {
      "source": "owner/repo",
      "sourceType": "github",
      "pluginName": "document-skills",  // ← From manifest
      "skillFolderHash": "abc123..."
    }
  }
}

​
In Skill Lists

The skills list command can group skills by plugin: 
$ skills list

Project Skills (.agents/skills/)

  document-skills
  • markdown-formatter
  • doc-generator

  web-skills  
  • react-best-practices

  (ungrouped)
  • standalone-skill

​
Implementation Details

​
Source Code

Plugin manifest support is implemented in src/plugin-manifest.ts: 
import { getPluginSkillPaths, getPluginGroupings } from './plugin-manifest';

// Get skill search directories from manifests
const searchDirs = await getPluginSkillPaths('/path/to/repo');
// Returns: [
//   '/path/to/repo/plugins/document-tools/skills/formatter',
//   '/path/to/repo/skills',  // conventional fallback
//   ...
// ]

// Get plugin name for each skill path
const groupings = await getPluginGroupings('/path/to/repo');
// Returns: Map<AbsolutePath, PluginName>
// Example: Map {
//   '/abs/path/to/skill' => 'document-skills'
// }

​
API

​
getPluginSkillPaths
function
Extract skill search directories from plugin manifests
​
getPluginGroupings
function
Get a map of skill paths to plugin names

​
Examples

​
Basic Marketplace

{
  "plugins": [
    {
      "name": "core-skills",
      "skills": [
        "./skills/formatter",
        "./skills/validator"
      ]
    }
  ]
}

​
Marketplace with Plugin Root

{
  "metadata": {
    "pluginRoot": "./packages"
  },
  "plugins": [
    {
      "name": "web-tools",
      "source": "./web",
      "skills": ["./skills/react"]
    },
    {
      "name": "api-tools",
      "source": "./api",
      "skills": ["./skills/rest"]
    }
  ]
}

​
Simple Plugin

{
  "name": "typescript-guide",
  "skills": [
    "./skills/setup",
    "./skills/best-practices",
    "./skills/testing"
  ]
}

Lock Files

See how pluginName is stored in lock files

Claude Code Plugins

Learn about the Claude Code plugin marketplace

Build docs developers (and LLMs) love

Get started for freeTalk to us