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

> Learn how to link a plugin manifest to its skill files in Claude Plugins. Define a skills array in plugin.json pointing to your SKILL.md files for seamless integration.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file, where each entry specifies the relative path to a directory containing a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file.

```json
{
  "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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) references multiple analytical capabilities:

```json
"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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file.
- **Validation**: The CI workflow at [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) enforces that all paths in `"skills"` resolve to valid directories with [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml)—will detect the missing directory or absent [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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.