Plugin Manifests

How the CLI discovers skills from Claude Code plugin manifests

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

Example Marketplace

{
  "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

Show Metadata Fields

pluginRoot · string

Base directory for all plugins. Must start with ./ (relative path)

Example: "./plugins"

plugins · array · required

Array of plugin definitions

Show Plugin Entry

name · string

Plugin name for grouping skills (e.g., "document-skills")

This name is stored in the lock file’s pluginName field.

source · string | object

Plugin location:

• String: Relative path starting with ./ (e.g., "./my-plugin")
• Object: Remote source with source and optional repo fields (skipped by CLI)

The CLI only processes local string paths.

skills · string[]

Array of skill paths relative to the plugin directory. Each path must start with ./

Example: ["./skills/formatter", "./skills/validator"]

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

Resolution Example

// 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

Example Plugin

{
  "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:

Resolution Example

// 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

Invalid Examples

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

{
  "skills": [
    "./skills/formatter",       // ✅ Relative, contained
    "./plugins/web/skill",      // ✅ Nested, contained
    "./skill"                   // ✅ Shallow, contained
  ]
}

---

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:

Global Lock File

{
  "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:

Example Output

$ 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:

Key Functions

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

Show Signature

async function getPluginSkillPaths(basePath: string): Promise<string[]>

basePath · string · required

Repository root directory

returns · string[]

Array of absolute paths to directories containing skills

getPluginGroupings · function

Get a map of skill paths to plugin names

Show Signature

async function getPluginGroupings(basePath: string): Promise<Map<string, string>>

basePath · string · required

Repository root directory

returns · Map<string, string>

Map of absolute skill path to plugin name

---

Examples

Basic Marketplace

.claude-plugin/marketplace.json

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

Marketplace with Plugin Root

.claude-plugin/marketplace.json

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

repo/
├── .claude-plugin/
│   └── marketplace.json
└── packages/
    ├── web/
    │   └── skills/
    │       └── react/
    │           └── SKILL.md
    └── api/
        └── skills/
            └── rest/
                └── SKILL.md

Simple Plugin

.claude-plugin/plugin.json

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

---

Related Documentation

Lock Files

See how pluginName is stored in lock files

Claude Code Plugins

Learn about the Claude Code plugin marketplace