How the Claude Code Plugin System Loads and Applies Skills from the Marketplace

Claude Code discovers plugins through marketplace.json manifests, installs them via plugin.json declarations, and applies individual skills defined in SKILL.md files to augment coding sessions.

The multica-ai/andrej-karpathy-skills repository demonstrates how the Claude Code plugin system transforms standalone repositories into reusable coding skills. When you load a plugin from the marketplace, Claude Code follows a strict discovery and registration pipeline that converts static markdown files into actionable context for your AI-assisted workflows.

Marketplace Registration and Discovery

The marketplace.json Manifest

Every Claude Code plugin begins its lifecycle as a marketplace entry. The repository must contain a .claude-plugin/marketplace.json file that registers the plugin with the Claude Code marketplace. This JSON file specifies the plugin's name, unique ID, author, and version metadata.

When you execute the marketplace command, Claude Code reads this manifest to make the plugin discoverable without cloning the entire repository. In the andrej-karpathy-skills repository, this file lives at .claude-plugin/marketplace.json, establishing the plugin's identity before any code reaches your local environment.

Installing and Loading Plugins

Adding Remote Marketplace Entries

Before installing skills, you must register the remote source with Claude Code. Use the marketplace add command to point Claude Code to the plugin repository:

/plugin marketplace add forrestchang/andrej-karpathy-skills

This command tells Claude Code where to fetch the plugin's manifest and prepares the system for skill installation.

The plugin.json Configuration

Once you trigger installation, Claude Code clones the repository and searches for .claude-plugin/plugin.json at the root. This file declares the plugin metadata and, crucially, defines an array of skill paths that tell Claude Code where to find individual skills.

The plugin.json in andrej-karpathy-skills lists directories such as "./skills/karpathy-guidelines", directing the loader to specific skill definitions within the repository structure.

Skill Discovery and Application

Parsing SKILL.md Files

For each entry in the skills array, Claude Code loads the designated directory as a discrete skill. Inside each skill directory, a SKILL.md file follows a strict schema that defines:

• Name: The skill identifier used for invocation
• Description: Human-readable explanation of the skill's purpose
• License: Usage rights for the skill content
• Markdown body: The actual instructions, guidelines, or context that Claude Code injects into your session

In the andrej-karpathy-skills repository, skills/karpathy-guidelines/SKILL.md contains the specific coding guidelines that Claude Code applies when you invoke the skill.

Runtime Registration

After parsing SKILL.md, Claude Code registers the skill under the name defined in the file header. The skill becomes immediately available to any active Claude Code session. You can invoke the registered knowledge using natural-language prompts such as:

"Apply the Karpathy guidelines to this code"

Claude Code retrieves the content from SKILL.md and applies the prescribed checks to your current coding context.

Updating Skills and Plugins

Running the install command again re-reads the manifest files and skill definitions. Any changes to SKILL.md or additions of new skill directories are automatically picked up without manual re-configuration. This ensures your skills stay synchronized with the repository's latest version.

Summary

• Marketplace discovery relies on .claude-plugin/marketplace.json to advertise plugin availability without full installation.
• Plugin installation clones the repository and parses .claude-plugin/plugin.json to identify skill locations.
• Skill loading processes each SKILL.md file to extract reusable coding knowledge and metadata.
• Runtime application registers skills by name, making them available through natural language prompts within Claude Code sessions.

Frequently Asked Questions

What file format defines a Claude Code skill?

Claude Code skills are defined in SKILL.md files. These markdown files follow a specific schema containing YAML frontmatter with fields for name, description, and license, followed by the skill's instructional content. The file resides in a dedicated skill directory referenced by the plugin's plugin.json configuration.

How does Claude Code know which skills are available in a plugin?

Claude Code determines available skills through the skills array in .claude-plugin/plugin.json. This JSON file lists relative paths to skill directories, such as "./skills/karpathy-guidelines". Claude Code iterates through these paths during installation to locate and parse each corresponding SKILL.md file.

Can I update a skill without reinstalling the entire plugin?

No, Claude Code requires you to run the install command again to pick up changes. However, re-running /plugin install andrej-karpathy-skills@karpathy-skills re-reads the manifest files and skill definitions, automatically updating any modified SKILL.md content or newly added skill directories without requiring you to remove and re-add the marketplace entry.

Where does the marketplace.json file live in a plugin repository?

The marketplace.json file must reside in the .claude-plugin/marketplace.json path at the repository root. This location is mandatory for marketplace registration, as Claude Code specifically searches for this file to extract the plugin's name, ID, author, and version metadata when you add the repository to your marketplace sources.

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