Plugins and Skills: A Three-Layer Extensibility Architecture

The Problem

When you type /simplify in Claude Code, it automatically performs a three-dimensional review of your recently modified code — code reuse, quality, and efficiency. When you install a Plugin, its Skills automatically appear in the available list. When an MCP Server exposes Prompts with specific frontmatter markers, those Prompts are also transformed into Skills for the model to invoke.

Behind all this is a three-layer extensibility architecture:

• Skill layer: Skill definitions carried in Markdown files, with metadata declared via frontmatter, supporting multi-source loading, argument substitution, and conditional activation
• Plugin layer: Bundles multiple Skills, Hooks, and MCP Servers into installable extension units, split into Built-in and Marketplace tiers
• MCP layer: Dynamically discovers and loads Skills from remote Servers via the MCP protocol

Each layer has its own independent registration mechanism, but they all ultimately converge into a single Command[] array, with SkillTool serving as the sole entry point to expose them to the model. This article starts from Skill system file loading and progressively dives into the design and implementation of this extensibility architecture.

Skill System Overview

Core Data Structure: Command

All Skills are ultimately represented as the Command type. Understanding this type is foundational to understanding the entire system:

The source field marks where the Skill comes from — 'bundled' indicates a skill compiled into the CLI binary, 'plugin' comes from a Plugin, 'mcp' from an MCP Server, and SettingSource values ('userSettings', 'projectSettings', 'policySettings') correspond to file Skills loaded from different directories.

getPromptForCommand is the core method: it accepts user arguments and tool context, returning prompt content to inject into the conversation. Skills from different sources implement their own argument substitution, shell command execution, and security policies within this method.

Multi-Source Loading Architecture

Loading priority follows this order, with the first-loaded Skill winning when names collide.

File Skill Loading: loadSkillsDir.ts

The core loading logic for file Skills lives in loadSkillsDir.ts. This file exceeds 1000 lines and is the most complex module in the entire Skill system.

Directory Structure Convention

The Skills directory only supports the directory format: each Skill is a directory containing a SKILL.md file.

The loading function loadSkillsFromSkillsDir traverses the directory, reading each SKILL.md:

Note several design points:

1. Directory format only. Single .md files in the /skills/ directory are ignored, ensuring each Skill can carry supporting files (scripts, templates, etc.).
2. Symbolic link support. The isSymbolicLink() check enables Skills to be shared via symlinks.
3. Parallel loading. Promise.all reads all Skill files concurrently.
4. Graceful degradation. A loading failure for one Skill doesn't affect the others.

Frontmatter Metadata Parsing

The SKILL.md file's frontmatter is the complete declaration of a Skill's behavior. The parseSkillFrontmatterFields function handles all possible fields:

A complete SKILL.md frontmatter example:

The semantics of these frontmatter fields are worth explaining one by one:

Argument Substitution Mechanism

Skill prompt content supports multiple argument substitution patterns:

There are three layers of substitution:

1. User arguments: $ARGUMENTS is replaced with the full argument string, $1/$2 with positional arguments, and named arguments like ${branch} with their corresponding values.
2. Built-in variables: ${CLAUDE_SKILL_DIR} points to the Skill's directory, and ${CLAUDE_SESSION_ID} is the current session ID.
3. Shell commands: The !`command` and ```! command ``` syntax within Skill content is actually executed, with output substituted into the prompt. This is a key capability for Skills to interact with the environment — but for security reasons, MCP-sourced Skills are prohibited from executing shell commands.

Multi-Level Source Aggregation and Deduplication

getSkillDirCommands is the aggregation entry point for file Skills. It uses memoize to cache results and loads Skills from five sources in parallel:

Note the source priority order: Managed (enterprise policy) > User (user global) > Project (project-level) > Additional (--add-dir) > Legacy (old /commands/).

Realpath-Based Deduplication

Multiple sources may point to the same file through different paths (e.g., via symlink). The system uses realpath to resolve to canonical paths for deduplication:

The deduplication process first computes identities for all files in parallel, then synchronously scans to remove duplicates:

This design chose realpath over inode comparison because some filesystems (NFS, ExFAT, container virtual FS) report unreliable inode values. The pattern of doing IO in parallel first (Promise.all for identities), then synchronous logic (iterative deduplication), is a typical approach that balances performance and correctness.

Paths Conditional Activation

Skills can declare via paths frontmatter that they should only be active under specific file paths:

When a Skill has a paths field, it's not immediately loaded into the available list but stored in a conditionalSkills Map. Only when the model operates on files matching the paths is the Skill activated:

This uses the ignore library (the same glob matching rules as .gitignore). After matching, the Skill is moved from conditionalSkills to dynamicSkills, and other modules are notified via a signal to clear caches. The activatedConditionalSkillNames Set ensures that when Skills are reloaded (after cache clearing), already-activated Skills won't be demoted back to conditional.

This "lazy activation" design has a clear performance purpose: a project may have many Skills, but not all are relevant to the current work. Through path filtering, the Skill list stays lean, reducing token consumption in the system prompt.

Dynamic Skill Discovery

Beyond conditional activation, the system also supports dynamically discovering new Skill directories from file operations:

When the model Reads or Edits a file like src/modules/payments/handler.ts, the system checks upward for src/modules/payments/.claude/skills/, src/modules/.claude/skills/, and so on. If new Skill directories are found, they're loaded and merged into the available Skills.

Worth noting is that the dynamicSkillDirs Set also records directories that have been checked (whether successfully or not), avoiding duplicate stat calls to the same directory. Additionally, Skill directories under .gitignore paths are skipped, preventing malicious Skills in node_modules from being loaded.

Effort Level

Skills can control the model's reasoning effort level via the effort frontmatter:

When a Skill runs with context: fork, effort is injected into the sub-Agent's definition:

This allows specific Skills to demand higher or lower reasoning intensity — for example, a code review Skill might set effort: high, while a simple formatting Skill sets effort: low for faster execution.

Bundled Skill System

The registerBundledSkill Registration Pattern

Bundled Skills are compiled into the CLI binary and don't depend on the filesystem. They're registered at startup via the registerBundledSkill function:

There's an elegant lazy file extraction mechanism here: when a Bundled Skill declares files (reference files), these files aren't written to disk at registration time but extracted on first invocation. extractionPromise ??= ... uses the nullish assignment operator for memoization — multiple concurrent invocations share the same Promise without duplicate extraction.

Secure File Writing

When extracting files to disk, the system employs multiple layers of security measures:

• O_EXCL: Fails if the file already exists, preventing overwrite of pre-created malicious files
• O_NOFOLLOW: Doesn't follow symbolic links, preventing symlink attacks
• 0o600: File permissions restricted to owner read/write
• 0o700: Directory permissions restricted to owner only

Path validation is equally strict:

Bundled Skill Registration Flow

All Bundled Skills are registered in initBundledSkills:

There are two registration patterns:

1. Unconditional registration: Always-available Skills like registerSimplifySkill() are imported at the module top level
2. Feature-gated registration: Uses feature() to check feature flags, with require() for lazy loading

require() is used instead of import() because after Bun bundling, dynamic import() path resolution points to /$bunfs/root/..., while require() works correctly.

Practical Example: The simplify Skill

Let's see how an actual Bundled Skill works:

SIMPLIFY_PROMPT is a carefully designed multi-stage prompt that instructs the model to:

1. Run git diff to identify changes
2. Launch three parallel Agents to review code reuse, code quality, and efficiency respectively
3. Summarize findings and directly fix issues

This demonstrates the core value of Bundled Skills: encapsulating expert-level multi-step workflows into a single command.

Plugin System

Two-Tier Plugin Architecture

Built-in Plugin

The key difference between Built-in Plugins and Bundled Skills is: users can enable/disable Built-in Plugins.

A Built-in Plugin can contain multiple components:

• skills: A list of skills defined via BundledSkillDefinition
• hooks: Lifecycle hook configuration
• mcpServers: MCP Server configuration

Plugin IDs use the {name}@builtin format, distinguishing them from Marketplace Plugins' {name}@{marketplace}.

Enable/Disable State Management

The state determination chain: isAvailable() -> userSetting -> defaultEnabled -> true. If isAvailable() returns false, the Plugin is completely invisible; otherwise the user's setting in the /plugin UI takes priority, falling back to the Plugin's default value, with a final fallback to enabled.

Skill Conversion from Plugin to Command

Plugin Skills are converted to standard Command objects via skillDefinitionToCommand:

The choice of source: 'bundled' here is deliberate — a code comment explains why: 'builtin' in Command.source semantics means hardcoded CLI commands (/help, /clear); if Plugin Skills used 'builtin', they would disappear from the SkillTool list.

Marketplace Plugin

Marketplace Plugins are represented by the LoadedPlugin type, with a richer structure:

Marketplace Plugins are distributed via Git repositories. The installation process clones the repository locally, reads the manifest file, then loads various components based on paths declared in the manifest. Skill files use the same directory format as project-level Skills (skill-name/SKILL.md), handled by the same loadSkillsFromSkillsDir loader.

Plugin namespacing uses colon separation: if a Plugin named ralph-loop provides help and cancel-ralph Skills, their full names are ralph-loop:help and ralph-loop:cancel-ralph.

MCP Skill Bridging

mcpSkillBuilders Registration

MCP Servers can expose Skills through the Prompt primitive. When an MCP Prompt's frontmatter contains specific fields, it gets transformed into a Skill rather than a regular Prompt:

This module solves a subtle circular dependency problem. The MCP code needs to call createSkillCommand and parseSkillFrontmatterFields, but directly importing loadSkillsDir.ts would bring in a massive transitive dependency tree, producing numerous circular warnings in dependency-cruiser checks.

The solution is runtime registration: mcpSkillBuilders.ts only imports types (typeof), creating no runtime dependency. loadSkillsDir.ts registers the actual functions during module initialization, which happens before any MCP Server connects.

Differences Between MCP Skills and File Skills

MCP-sourced Skills have two important restrictions:

1. Shell command execution is prohibited:

2. ${CLAUDE_SKILL_DIR} is meaningless: MCP Skills have no local directory, so the Skill directory variable is not substituted.

MCP Skills are retrieved in SkillTool.call() via getAllCommands, which filters loadedFrom === 'mcp' commands from AppState.mcp.commands:

uniqBy deduplicates by name, with local commands taking priority (appearing first in the array).

SkillTool Execution Flow

Execution Modes

SkillTool is the sole tool interface through which the model invokes Skills. It supports two execution modes:

sequenceDiagram
    participant M as Model
    participant ST as SkillTool
    participant V as validateInput
    participant P as checkPermissions
    participant C as call()

    M->>ST: { skill: "simplify", args: "" }
    ST->>V: Verify Skill exists
    V-->>ST: result: true

    ST->>P: Permission check
    alt Safe-attribute Skill
        P-->>ST: allow (auto)
    else Has allow rule
        P-->>ST: allow (rule)
    else Needs user confirmation
        P-->>ST: ask
    end

    ST->>C: Execute Skill

    alt context: 'fork'
        C->>C: executeForkedSkill()
        Note over C: Runs in sub-Agent<br/>Independent token budget
        C-->>ST: { status: 'forked', result: "..." }
    else context: 'inline' (default)
        C->>C: processPromptSlashCommand()
        Note over C: Expands prompt into<br/>current conversation context
        C-->>ST: { status: 'inline', newMessages: [...] }
    end

    ST-->>M: ToolResult

    style M fill:#1e3a5f,color:#e0e0e0
    style ST fill:#2d1f3d,color:#e0e0e0
    style V fill:#1a3d2e,color:#e0e0e0
    style P fill:#3d2e1a,color:#e0e0e0
    style C fill:#3d1a1a,color:#e0e0e0

Inline Mode (Default)

Inline mode expands the Skill's prompt content into the current conversation context:

Results are returned as newMessages, which are inserted into the current conversation flow. The context is simultaneously modified via contextModifier — adding allowedTools and passing through the effort level.

Fork Mode

When a Skill declares context: 'fork', it executes in an independent sub-Agent:

Advantages of Fork mode:

• Independent token budget: The sub-Agent has its own context window, not consuming the main conversation's tokens
• Isolation: Tool calls and intermediate results during Skill execution don't pollute the main conversation
• Memory management: After completion, agentMessages.length = 0 proactively releases message memory, and clearInvokedSkillsForAgent(agentId) cleans up Skill state

Permission Checking

SkillTool's permission checking distinguishes several scenarios:

1. Deny rules checked first: If the user or policy has configured a deny rule (e.g., Skill(deploy)), reject immediately
2. Safe attributes auto-allow: If the Skill has only safe attributes (no allowedTools, no hooks, no context: fork), allow automatically
3. Allow rule matching: Match user-configured allow rules, supporting prefix wildcards (review:* matches all Skills starting with review:)
4. Ask as fallback: Default to asking the user, providing both "allow this Skill" and "allow this prefix" as shortcut suggestions

Skill Listing and Token Budget Management

Skill discovery information is exposed to the model through system-reminder messages. However, there may be many Skills, and listing full descriptions for all of them would waste precious context window tokens. prompt.ts implements a budget management mechanism:

When total Skill descriptions exceed the budget, the system employs a tiered truncation strategy:

Design principles:

• Bundled Skills are never truncated: They are core capabilities, and description quality directly affects the model's invocation decisions
• Progressive degradation: First truncate description length, in extreme cases keep only names
• Per-description limit of 250 characters: MAX_LISTING_DESC_CHARS hard limit, no waste even when budget is ample

Unification and Interaction of the Three Layers

Unified Command Registration

The three layers ultimately unify through the getCommands() function:

SkillTool.getAllCommands() further adds MCP Skills:

Name Collision Resolution

Same-named Skills may appear across layers. The resolution strategy is: first registered wins.

• Within file Skills: Managed > User > Project (determined by flatten order in getSkillDirCommands)
• File vs Bundled: File Skills come first in getCommands
• Local vs MCP: uniqBy([...localCommands, ...mcpSkills], 'name') gives local priority

Plugin Skills avoid conflicts with other sources through namespacing (plugin-name:skill-name).

Hooks Unification

Both Skills and Plugins can declare Hooks. Skill Hooks are registered when invoked, while Plugin Hooks take effect as soon as they're loaded:

Both use the same HooksSettings Schema and can configure PreToolUse, PostToolUse, PreCompact, and other lifecycle hooks.

Caching and Invalidation

File Skill loading results are cached via memoize, but dynamic Skill discovery and conditional Skill activation need to trigger cache invalidation:

After dynamic Skill loading completes, subscribers are notified via a signal:

This signal mechanism uses the same createSignal utility as GrowthBook feature flags — a lightweight observer pattern implementation. Subscriber errors are caught and logged without interrupting signal propagation.

Bare Mode and Policy Lockdown

Bare Mode

--bare mode skips all auto-discovery logic, only loading Skills explicitly specified via --add-dir:

This is useful for CI/CD environments: ensuring only predefined Skills run, unaffected by project directory structure.

Plugin-Only Policy

Enterprises can lock Skill sources to Plugin-only via isRestrictedToPluginOnly('skills'):

When skillsLocked is true:

• Project-level Skills (.claude/skills/) are not loaded
• User-level Skills (~/.claude/skills/) are not loaded
• Legacy commands directories are not loaded
• Only Managed (policy) level Skills and Bundled/Plugin Skills are available

Portable Patterns

Claude Code's three-layer extensibility architecture contains several reusable design patterns:

1. Markdown-as-Config Pattern

Using Markdown files (with YAML frontmatter) as a configuration carrier:

Advantages of this pattern:

• Human-readable: Non-developers can write and maintain Skills
• Version control friendly: Markdown diffs are clear and intuitive
• Self-documenting: Frontmatter is configuration, body is documentation
• IDE support: Standard Markdown format with rich editor support

2. Multi-Level Directory Merge Pattern

Loading configuration from multiple directory levels, merging with priority-based deduplication:

This pattern is applicable to any system needing "global defaults + project overrides" semantics. Deduplication uses realpath rather than path string comparison, correctly handling symlink scenarios.

3. Conditional Activation Pattern

Resources (Skills, rules, etc.) aren't loaded immediately but declare activation conditions that only take effect when matched at runtime:

This pattern is particularly valuable in large projects. It compresses the Skill list from O(N) to O(active) level while maintaining the ability for on-demand discovery.

4. Register-Rather-Than-Import Pattern

Both Bundled Skills and MCP Skill Builders use the pattern of "registering to a global Map during module initialization rather than importing directly":

Benefits of this pattern:

• Breaks circular dependencies: The registration module only imports types, not implementations
• Supports lazy loading: Feature-gated Skills use require() for on-demand loading
• Test-friendly: clearBundledSkills() can reset state

5. Secure Write Pattern

Bundled Skill file extraction demonstrates secure writing best practices:

Four layers of defense:

1. Random directory names prevent pre-creation attacks
2. O_EXCL prevents overwriting existing files
3. O_NOFOLLOW prevents symbolic link attacks
4. Path normalization + .. checking prevents directory traversal

Summary

Claude Code's three-layer extensibility architecture — Skills, Plugins, MCP — may seem complex, but the underlying logic is clear:

1. Unified representation: All extensible capabilities ultimately become the Command type
2. Unified entry point: SkillTool is the sole interface through which the model invokes Skills
3. Unified dispatch: Regardless of source, Skill execution goes through the same validation, permission checking, and inline/fork decisions
4. Differentiated security: Different sources have different trust levels (MCP prohibits shell commands, Plugins require permission confirmation, Bundled auto-allow)

The design philosophy of this architecture is: let users define new capabilities through Markdown files, let third parties extend the ecosystem through Plugins and MCP, while maintaining clear security boundaries at every layer. File Skill path conditional activation and dynamic discovery ensure performance in large projects, Bundled Skill lazy extraction and secure writing ensure reliability for binary distribution, and the Plugin two-tier architecture (Built-in + Marketplace) balances out-of-the-box experience with extensibility freedom.

The next article will dive into the OAuth and authentication system, exploring how Claude Code securely manages API keys, OAuth tokens, and session credentials.