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

The 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 files.

The anthropics/financial-services repository implements a lightweight, filesystem-driven plugin architecture for Claude. Understanding the 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. 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:

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

The repository's linting script (scripts/check.py) validates that every plugin directory contains a properly formatted 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 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 is required; the engine relies entirely on this directory layout.

Validation with scripts/check.py

The 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. 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:

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

Adding a New Skill

Create the directory structure and add your skill definition:

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

Populate SKILL.md with the skill's instructions and metadata.

Running Validation and Sync

After adding skills, execute the maintenance scripts:

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:

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 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 file.
• Validation occurs through 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, copying definitions from vertical sources to agent bundles.

Frequently Asked Questions

What fields are required in plugin.json?

The 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.

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 file. If present, the system automatically registers that folder as an invokable skill. This eliminates the need to list skills in plugin.json and allows dynamic skill addition by simply creating new directories.

What happens if a skill path is invalid?

The 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 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 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.

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