# plugin.json Schema Structure and Skill Discovery in Anthropic's Financial-Services Repository

> Explore the plugin.json schema structure in Anthropic's financial-services repo. Learn how Claude automatically discovers skills from SKILL.md files within the skills directory.

- Repository: [Anthropic/financial-services](https://github.com/anthropics/financial-services)
- Tags: api-reference
- Published: 2026-05-07

---

**The [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) manifest requires four mandatory fields—`name`, `version`, `description`, and `author`—while skills are automatically discovered when the Claude runtime detects a `skills/` directory containing subfolders with [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) files.**

The `anthropics/financial-services` repository implements a lightweight, filesystem-driven plugin architecture for Claude. Understanding the [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) schema structure and skill discovery mechanism is essential for developers building financial-services verticals or agent plugins, as these conventions determine how capabilities are registered and invoked.

## plugin.json Schema Structure and Required Fields

Every plugin in the repository must include a manifest file located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/financial-services/blob/main/.claude-plugin/plugin.json). This file serves as the source of truth for the plugin's identity and metadata.

### Mandatory Fields

The schema is deliberately minimal, requiring only four top-level fields:

- **`name`**: A unique string identifier used for marketplace listing and plugin invocation (e.g., `/plugin:wealth-management`).
- **`version`**: A semantic version string (e.g., `0.1.0`) for change tracking.
- **`description`**: A human-readable summary displayed in the Claude UI.
- **`author`**: An object containing at minimum a `name` string identifying the plugin owner.

A complete example from the wealth-management vertical demonstrates this structure:

```json
{
  "name": "wealth-management",
  "version": "0.1.0",
  "description": "Wealth management and financial advisory tools: client reviews, financial planning, portfolio analysis, and client reporting",
  "author": {
    "name": "Anthropic FSI"
  }
}

```

> **Source:** [`plugins/vertical-plugins/wealth-management/.claude-plugin/plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugins/vertical-plugins/wealth-management/.claude-plugin/plugin.json)

The repository's linting script ([`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py)) validates that every plugin directory contains a properly formatted [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) conforming to this minimal schema.

## How Skills Are Discovered

Skills are MD-driven knowledge modules discovered through filesystem conventions rather than explicit declarations in the manifest.

### Convention-Based Discovery via the skills/ Directory

When Claude loads a plugin, the runtime walks the plugin's file tree looking for a top-level `skills/` folder. Each immediate subdirectory within `skills/` represents an individual skill. For example, the portfolio-rebalance skill resides at:

```

plugins/vertical-plugins/wealth-management/skills/portfolio-rebalance/SKILL.md

```

### SKILL.md as the Skill Definition

Each skill folder must contain a [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) file that defines the skill's description, system prompts, and auxiliary data. The runtime automatically registers any directory containing this file as an invokable capability. No explicit enumeration in [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) is required; the engine relies entirely on this directory layout.

### Validation with scripts/check.py

The [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) utility enforces integrity by verifying that every skill path referenced in plugin YAML manifests points to an existing folder. If a skill is missing, the lint step fails, preventing broken references from being committed. This validation logic appears around lines 94-100 in the script.

### Syncing Vertical Skills to Agent Plugins

For **agent-plugins** (named agents), skills propagate from vertical sources via [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py). This script copies skill definitions from `vertical-plugins/<vertical>/skills/` into the corresponding agent's `skills/` folder. This ensures compiled agent bundles contain a snapshot of the latest definitions while maintaining the vertical plugin as the single source of truth.

## Implementation Examples

### Creating a Minimal plugin.json

To register a new plugin, create the manifest with the four required fields:

```json
{
  "name": "my-plugin",
  "version": "0.0.1",
  "description": "Brief description of what the plugin does",
  "author": { "name": "My Organization" }
}

```

Save this file to [`plugins/vertical-plugins/my-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugins/vertical-plugins/my-plugin/.claude-plugin/plugin.json).

### Adding a New Skill

Create the directory structure and add your skill definition:

```text
plugins/vertical-plugins/my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-new-skill/
        └── SKILL.md

```

Populate [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) with the skill's instructions and metadata.

### Running Validation and Sync

After adding skills, execute the maintenance scripts:

```bash
python3 scripts/check.py              # Validates plugin.json and skill paths

python3 scripts/sync-agent-skills.py  # Propagates skills to agent bundles

```

The runtime discovery process operates similarly to this Python pseudocode:

```python
for root, dirs, files in os.walk(plugin_path):
    if "skills" in dirs:
        skill_root = os.path.join(root, "skills")
        for skill_dir in os.listdir(skill_root):
            if os.path.isfile(os.path.join(skill_root, skill_dir, "SKILL.md")):
                register_skill(plugin_name, skill_dir)

```

## Summary

- **[`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json)** requires four mandatory fields (`name`, `version`, `description`, `author`) and resides in the `.claude-plugin/` directory.
- **Skill discovery** is filesystem-driven: the Claude runtime automatically registers any subdirectory under `skills/` that contains a [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) file.
- **Validation** occurs through [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py), which ensures all referenced skill paths exist before deployment.
- **Skill propagation** to agent plugins is handled by [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py), copying definitions from vertical sources to agent bundles.

## Frequently Asked Questions

### What fields are required in plugin.json?

The [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) schema requires exactly four fields: `name` (unique identifier), `version` (semantic versioning), `description` (human-readable summary), and `author` (object containing a `name` string). Optional properties are reserved for future extensions, but the current implementation enforces only these mandatory fields through [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py).

### How does the Claude runtime find skills without explicit registration?

The runtime implements convention-based discovery by traversing the plugin's directory tree. When it encounters a `skills/` folder, it examines each subdirectory for a [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) file. If present, the system automatically registers that folder as an invokable skill. This eliminates the need to list skills in [`plugin.json`](https://github.com/anthropics/financial-services/blob/main/plugin.json) and allows dynamic skill addition by simply creating new directories.

### What happens if a skill path is invalid?

The [`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py) linting utility validates all skill references during the build process. If a skill path referenced in a plugin's configuration points to a non-existent directory or missing [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) file, the validation fails and prevents the plugin from being deployed. This ensures that all registered capabilities have corresponding source files.

### How do agent plugins get their skills?

Agent plugins receive their skills through the [`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/scripts/sync-agent-skills.py) synchronization script. This utility copies skill definitions from the source vertical plugins (located at `vertical-plugins/<vertical>/skills/`) into the agent plugin's own `skills/` directory. This architecture maintains vertical plugins as the canonical source of truth while allowing agents to bundle specific capabilities.