# How Skills Get Loaded and Activated for Claude Plugins: A Complete Technical Guide

> Discover how Claude plugins load and activate skills via manifest-driven discovery using plugin.json and SKILL.md. Learn about JSON schema validation and subprocess execution.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-08

---

**Claude plugins load and activate skills through a manifest-driven discovery process that parses [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) to register capabilities defined in individual [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files, activating them via JSON schema validation and subprocess execution when matched during conversations.**

Understanding how skills get loaded and activated for Claude plugins is essential for developers extending the `anthropics/claude-plugins-community` repository. The architecture relies on a convention-based directory structure where plugin manifests declare available capabilities, and individual skill definitions specify execution logic and validation schemas. This system enables Claude to dynamically discover, validate, and invoke external functionality without hard-coded integration logic.

## Plugin Discovery and Manifest Structure

The loading sequence begins when Claude's runtime scans the workspace for plugin packages. Each valid plugin must contain a hidden `.claude-plugin` directory at its root, signaling to the system that a manifest file is available for inspection.

### The .claude-plugin Directory Convention

Claude identifies plugins by locating [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) files within `.claude-plugin` directories. For example, in the `quickdesign` plugin, the file path [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) serves as the entry point that declares the plugin's metadata and skill inventory.

### Parsing plugin.json

The manifest file contains a `skills` array that maps skill names to their respective definition directories. According to the source structure in `anthropics/claude-plugins-community`, this JSON configuration establishes the contract between the plugin package and Claude's runtime.

Example structure from [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json):

```json
{
  "name": "quickdesign",
  "version": "0.1",
  "skills": [
    { "name": "quickdesign", "path": "skills/quickdesign" }
  ]
}

```

## Skill Definition Loading

Once the manifest identifies available skills, Claude loads individual definitions from the paths specified in the [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) skills array. Each skill directory must contain a [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file that defines the contract between Claude and the execution script.

### The SKILL.md Specification

The [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file uses structured markdown to declare three critical components: **input parameters** as JSON Schema, **output descriptions**, and the **execution script** path. For example, [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) specifies validation rules and the relative path to the runtime script.

Example structure:

```markdown

# QuickDesign Skill

**Inputs**

```json
{
  "type": "object",
  "properties": {
    "prompt": { "type": "string", "description": "Design brief" }
  },
  "required": ["prompt"]
}

```

**Script**
`scripts/run_quickdesign.py`

```

### Input Schema and Execution Mapping

The JSON schema defined in the **Inputs** section enforces type safety before script execution. The **Script** field provides a relative path (e.g., [`scripts/run_quickdesign.py`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/run_quickdesign.py)) that the dispatcher resolves against the skill directory to locate the executable implementation.

## Runtime Registration and Activation

After parsing skill definitions, Claude registers each capability with an internal dispatcher keyed by the skill name. This registration process stores the JSON schema for input validation and the absolute filesystem path to the execution script.

### The Internal Dispatcher

The dispatcher maintains a registry mapping skill names to their validation schemas and script locations. When `load_plugin()` processes the manifest, it extracts these components from [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) and populates the dispatcher using the skill name as the lookup key.

### Conversation-Time Invocation

When a user invokes a skill during chat, the dispatcher validates supplied arguments against the stored JSON schema. If validation passes, Claude spawns the script specified in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md), passing validated arguments via stdin or temporary JSON files.

The system captures the script's stdout, parses it as JSON, and returns the structured result to the conversation context for Claude to process.

## Error Handling and Validation

If user-provided arguments fail validation against the skill's JSON schema, Claude surfaces a structured error message to the conversation before executing the script. If the execution script returns non-JSON output or a non-zero exit status, Claude captures the error and presents a friendly failure message while preserving the chat flow.

## Implementation Example

The following pseudocode illustrates the internal loading and activation flow based on the `anthropics/claude-plugins-community` implementation:

**Loading phase:**

```python
def load_plugin(plugin_dir):
    manifest = json.load(open(f"{plugin_dir}/.claude-plugin/plugin.json"))
    for skill in manifest["skills"]:
        skill_path = f"{plugin_dir}/{skill['path']}"
        skill_md = open(f"{skill_path}/SKILL.md").read()
        # parse markdown to extract JSON schema & script path

        schema = extract_json_schema(skill_md)
        script = extract_script_path(skill_md)
        register_skill(skill["name"], schema, script)

```

**Activation phase:**

```python
def invoke_skill(name, args):
    schema, script = dispatcher[name]
    validate(args, schema)                     # raises if invalid

    result_json = subprocess.check_output(
        ["python", script], input=json.dumps(args).encode()
    )
    return json.loads(result_json)

```

## Summary

- **Manifest-driven discovery**: Claude locates plugins via [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) files in repository subdirectories, using the presence of this file to trigger the loading sequence.
- **Schema validation**: Each skill defines input requirements using JSON Schema in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md), ensuring type safety before script execution reaches the runtime environment.
- **Script isolation**: Skills execute as separate subprocesses (e.g., Python scripts like [`scripts/run_quickdesign.py`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/run_quickdesign.py)), communicating structured data via stdin and stdout using JSON.
- **Dynamic registration**: The internal dispatcher maintains a runtime registry of skill names mapped to their validation schemas and execution paths, enabling immediate lookup during conversations.

## Frequently Asked Questions

### What file triggers skill loading in Claude plugins?

The presence of [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) triggers the loading sequence. Claude's runtime recursively scans plugin directories for this specific file path to identify valid packages and parse their skill declarations.

### How does Claude know which script to run for a skill?

Each skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file contains a **Script** section specifying the relative path to the executable (e.g., [`scripts/run_quickdesign.py`](https://github.com/anthropics/claude-plugins-community/blob/main/scripts/run_quickdesign.py)). The dispatcher resolves this path relative to the skill directory and executes it as a subprocess during activation.

### Can a single plugin contain multiple skills?

Yes. The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest supports a `skills` array containing multiple entries, each with a unique name and filesystem path. This allows plugins to bundle related capabilities under a single package while maintaining separate definitions and execution scripts for each skill.

### What happens if skill input validation fails?

If user-provided arguments do not match the JSON Schema defined in the skill's [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md), Claude returns a validation error to the conversation before executing the script. This prevents malformed data from reaching the execution environment and provides immediate feedback to correct the input parameters.