Text of code.claude.com › docs › en › plugins › components as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Add components to a plugin - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A Claude Code plugin is built from components, such as skills, agents, hooks, and MCP servers. Each component has a default folder in the plugin, an optional manifest key in .claude-plugin/plugin.json that replaces or adds to that folder, and a name the user sees.

For each key’s full field table, see the manifest reference . Use this page to add a component to a plugin that already loads. After you add a component, run /reload-plugins in a running session or start a new one so Claude Code loads it. To check the component’s file before loading it, run claude plugin validate . in your shell from the plugin directory. These cases are covered on other pages: Building your first plugin : start with Create a plugin Installing someone else’s plugin : see Install plugins Your plugin’s users are on claude.ai or in Cowork : a different set of components loads there.

See Plugin structure and testing and the component support table Explore the plugin directory The explorer shows an example plugin, my-plugin , that has these components in their default locations: A review skill and an about command A security-review subagent A hook that formats files after Claude edits them, and the scripts/ folder it calls A log monitor An output style and a color theme A route-audit workflow A hello-plugin executable A local MCP server and a Go language server Each file is the smallest valid example of its format, there to show the shape rather than to be useful: a real skill or agent carries full instructions and often supporting files, and a real hook or monitor does real work.

The sections after the explorer use the same files as their examples and link to fuller ones. Select a file or folder to read what it’s for, see what goes in it, and find the section that covers it. Add each kind of component Each section below covers one kind of component: where its files go in the plugin, an example that validates, what the user sees once the plugin loads, and the manifest key that changes the default location.

Add the ones your plugin needs; none is required. Skills A skill is a SKILL.md file that Claude can load when its description matches the task. The user can also run it as a command. Save each skill in its own directory under skills/ : my-plugin/ ├── .claude-plugin/ │ └── plugin.json └── skills/ └── review/ └── SKILL.md Give the SKILL.md a description so Claude knows when to use it: skills/review/SKILL.md --- description : Reviews a pull request for style and test coverage.

Use when asked to review code. --- Review the changed files. Report style problems first, then missing tests. After you load the plugin, /my-plugin:review runs the skill. The command name and who can invoke it follow these rules: Command name : /<plugin>:<directory> , so skills/review/SKILL.md in my-plugin is /my-plugin:review . If you set name in the frontmatter, it replaces the last segment and the plugin prefix stays.

See how a skill gets its command name Who invokes it : Claude, the user, or both, controlled by frontmatter. See Control who invokes a skill You can also place skills outside the default skills/ directory: Additional directories : list them in the skills manifest key. They add to the default skills/ scan rather than replacing it, unlike commands and agents A single skill at the plugin root : with no skills/ directory and no skills manifest key, a SKILL.md at the plugin root loads as one skill.

Set name in its frontmatter, because otherwise a marketplace install names the skill after its cache directory rather than your plugin To include instructions in a plugin, write them as a skill. Claude Code doesn’t load a CLAUDE.md at the plugin root, and claude plugin validate warns CLAUDE.md at the plugin root is not loaded as project context . If a rule must hold every time, such as blocking edits to protected files , add it to the plugin as a hook rather than a skill.

To choose between the two, see the Hook vs Skill tab under Compare similar features . For frontmatter fields and supporting files, see Skills . Commands A command is a single Markdown file the user runs by name, such as /my-plugin:about . Commands are the older format, and skills supersede them for new work. A skill runs by name the same way, and it can also carry supporting files in its directory. Keep commands/ for files you’re moving over from .claude/commands/ .

Save a command at commands/<file>.md and it becomes /<plugin>:<file> . A subdirectory adds a segment, so commands/db/migrate.md is /my-plugin:db:migrate . Command files take the same frontmatter as skills. Define commands in the manifest You only need this if you want to keep command files somewhere other than commands/ , or to define a short command inside plugin.json without a separate Markdown file. Set the commands manifest key, and Claude Code reads it instead of scanning commands/ .

The key takes a path, an array of paths, or an object that maps each command name to either a source file or inline content . This manifest defines /my-plugin:about inline, with no Markdown file: .claude-plugin/plugin.json { "name" : "my-plugin" , "commands" : { "about" : { "content" : "Summarize what this repository does in three sentences." , "description" : "Summarize the repository" } } } Load the plugin and run /my-plugin:about in the session to confirm it loaded.

For the full key syntax, see commands . Agents A subagent is a separate assistant, with its own instructions and context window, that Claude can delegate a task to. Each Markdown file under agents/ defines one: agents/security-reviewer.md --- name : security-reviewer description : Reviews code changes for security issues. Use after edits to authentication or input handling. model : sonnet --- You are a security reviewer.

Read the changed files and report injection, authentication, and secrets-handling risks. This agent is named my-plugin:security-reviewer , and the user can invoke it explicitly with @agent-my-plugin:security-reviewer . The name form is <plugin>:<name> , where <name> comes from the frontmatter name field, or from the file name when that field is missing. The agents manifest key replaces the agents/ scan. Organize agents in subfolders You can put plugin agent files in subfolders of agents/ .

Claude Code loads them recursively and joins the plugin name, each subfolder name, and the file name with colons to form the agent’s scoped name. For example, agents/review/security.md in a plugin named my-plugin loads as my-plugin:review:security . Two settings change that name: Frontmatter name : it replaces only the file name, so name: audit in agents/review/security.md loads as my-plugin:review:audit Manifest agents field: a file you list there loads without subfolder names, so "agents": "./custom/review/security.md" loads as my-plugin:security Frontmatter fields in plugin agents A plugin agent’s frontmatter follows these rules: Supported fields : name , description , model , effort , maxTurns , autoCompactWindow , tools , disallowedTools , skills , memory , background , omitClaudeMd , isolation , color , and the cacheTtl key of experimental .

The only valid isolation value is "worktree" . See supported frontmatter fields for what each one does Ignored fields : permissionMode , hooks , mcpServers , and initialPrompt . An agent file can’t add hooks or MCP servers on its own, so add those as plugin hooks and MCP servers instead A name longer than 256 characters : Claude Code ignores it and names the agent after its file, as it does when the field is missing Frontmatter that doesn’t parse : the agent still loads with every field ignored.

It’s named after the file, and its description reads Agent from my-plugin plugin . Run clau

The rest of this page is on the live site.