How to Link a Plugin Manifest to Its Skill Files in Claude Plugins

In the anthropics/claude-plugins-community repository, you link a plugin manifest to its skill files by defining a "skills" array in the .claude-plugin/plugin.json file, where each entry specifies the relative path to a directory containing a SKILL.md file.

The Claude Plugins Community repository organizes each plugin as a standalone top-level directory containing both metadata and executable capabilities. To expose your plugin's functionality to Claude, you must explicitly declare where your skill definitions reside within the plugin manifest. This article explains the exact mechanism for linking manifest files to their corresponding skill directories, as implemented in the anthropics/claude-plugins-community source code.

Understanding the Plugin Manifest Structure

The manifest serves as the single source of truth for plugin configuration and capability discovery.

The plugin.json File Location

Each plugin resides in its own directory (such as tres-finance-plugin, quickdesign, or eli5). At the root of this directory, the manifest file lives at .claude-plugin/plugin.json. This JSON file contains the plugin's metadata—including name, description, and icons—and the critical skills array that establishes the linkage to executable capabilities.

The Skills Array

The skills field is a JSON array of strings, where each string represents a relative path from the plugin root to a skill directory. When Claude loads the plugin, it iterates through this array, resolves each path, and registers the corresponding skill by reading its SKILL.md file.

Step-by-Step: Linking Skills to Your Manifest

Follow these concrete steps to establish proper manifest-to-skill linkage in your plugin project.

1. Define Skill Directories in plugin.json

Open your .claude-plugin/plugin.json file and add or modify the "skills" key. Each entry must be a relative path pointing to a folder that contains a SKILL.md file.

{
  "name": "tres-finance-plugin",
  "description": "Financial analysis tools for Tres",
  "skills": [
    "skills/tres-report-analyzer",
    "skills/tres-invoice-bill-matching"
  ]
}

In this example from the tres-finance-plugin, the manifest points to two distinct skill directories within the skills/ folder.

2. Create the Skill Directory and SKILL.md

For every path listed in the "skills" array, create the corresponding directory structure and include a SKILL.md file. This markdown file defines the skill's behavior, parameters, and execution logic.

tres-finance-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── tres-report-analyzer/
    │   └── SKILL.md
    └── tres-invoice-bill-matching/
        └── SKILL.md

3. Validate the Linkage

The repository enforces manifest integrity through automated validation. The CI workflow defined in .github/workflows/validate-plugins.yml executes a script that verifies every path in the "skills" array points to an existing directory containing a valid SKILL.md file. This prevents broken links between manifests and skill definitions from merging into the main branch.

Real-World Examples from the Repository

Examining existing plugins demonstrates the consistent pattern for manifest-to-skill linkage.

Tres Finance Plugin Example

The tres-finance-plugin demonstrates a multi-skill architecture. Its .claude-plugin/plugin.json references multiple analytical capabilities:

"skills": [
  "skills/tres-report-analyzer",
  "skills/tres-invoice-bill-matching"
]

Each path resolves to a subdirectory under tres-finance-plugin/skills/, such as skills/tres-report-analyzer/SKILL.md.

Quickdesign Plugin Example

The quickdesign plugin follows the same convention with a streamlined structure. Its manifest points to "skills/quickdesign", which contains the single skill definition file. Similarly, the eli5 plugin uses "skills/eli5" to link its explanation-generation capability.

How Path Resolution Works

When Claude processes a plugin, the loader treats each string in the "skills" array as a relative path from the plugin root directory. It concatenates the plugin root path with the specified string, navigates to the resulting directory, and attempts to read SKILL.md. If the directory or file is missing, the loader skips the entry or fails validation, depending on the execution context. This relative path mechanism ensures plugins remain portable and self-contained within the repository structure.

Summary

• Manifest location: .claude-plugin/plugin.json at the plugin root directory.
• Linkage mechanism: The "skills" array contains relative paths to skill directories.
• Required files: Each skill directory must contain a SKILL.md file.
• Validation: The CI workflow at .github/workflows/validate-plugins.yml enforces that all paths in "skills" resolve to valid directories with SKILL.md files.
• Examples: The tres-finance-plugin, quickdesign, and eli5 plugins demonstrate this pattern with paths like "skills/tres-report-analyzer" and "skills/quickdesign".

Frequently Asked Questions

What is the exact path for the plugin manifest file?

The plugin manifest must be located at .claude-plugin/plugin.json relative to the plugin's root directory. For example, in the tres-finance-plugin directory, the full path is tres-finance-plugin/.claude-plugin/plugin.json.

Can I use absolute paths in the skills array?

No, the "skills" array requires relative paths from the plugin root. The plugin loader resolves these paths dynamically against the plugin's installation directory, making absolute paths incompatible with the repository's portable architecture.

What happens if a skill path listed in the manifest does not exist?

The repository's validation script—executed via .github/workflows/validate-plugins.yml—will detect the missing directory or absent SKILL.md file and fail the CI check. This prevents merging plugins with broken skill linkages into the main branch.

Does every skill directory need a SKILL.md file?

Yes, every directory listed in the "skills" array must contain a SKILL.md file. This markdown file serves as the skill's definition document, and its presence is mandatory for the validation script to pass the plugin as valid.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}