Skip to content

plugin-skill-system.md

Latest commit

 

History

History
84 lines (68 loc) · 3.23 KB

plugin-skill-system.md

File metadata and controls

84 lines (68 loc) · 3.23 KB

Plugin & Skill System

Overview

Claude Code's extensibility is built on two complementary systems: Plugins (collections of commands, agents, and hooks) and Skills (single-purpose workflows defined in markdown). Both use a declarative, frontmatter-driven approach.

Plugin System

Plugin Sources

  • Marketplace plugins: Resolved by name (e.g., plugin@official), downloaded from official registry
  • Session plugins: Loaded from --plugin-dir CLI flag or SDK plugins option
  • Built-in plugins: Hardcoded in the binary

Plugin Structure

my-plugin/
├── plugin.json          # Metadata, version, dependencies
├── commands/            # Slash command .md files
│   └── my-command.md    # Frontmatter + prompt body
├── agents/              # Agent definition .md files
│   └── my-agent.md      # Frontmatter + agent prompt
└── hooks/
    └── hooks.json       # Hook definitions (pre-tool, post-tool)

Loading Pipeline

  1. Discovery: Scan all plugin sources, resolve symlinks
  2. Deduplication: File identity checks prevent duplicate loading
  3. Manifest validation: plugin.json parsed and verified
  4. Component registration: Commands, agents, hooks merged into runtime
  5. Caching: Marketplace plugins cached locally with version checking

Marketplace Policies

  • Blocklist/allowlist enforcement by organization policy
  • Version pinning support
  • Install count tracking via public stats endpoint

Skill System

What is a Skill?

A skill is a reusable workflow defined as a markdown file with YAML frontmatter:

---
name: my-skill
description: One-line description
whenToUse: When the user asks to...
---

Prompt content that defines the skill's behavior...

Skill Sources (in priority order)

  1. User config (~/.claude/skills/)
  2. Project settings (.claude/skills/)
  3. Plugin directories
  4. Bundled skills (shipped with Claude Code)
  5. Managed/policy skills (organization-level)

Skill Types

  • Prompt skills: Fork a sub-agent with the skill's prompt (primary type)
  • Shell scripts: Spawned in subprocess (deprecated, replaced by prompt skills)

Execution Flow

  1. User invokes /skill-name or LLM calls SkillTool
  2. Skill resolved by name from registry
  3. Arguments substituted into prompt template
  4. Sub-agent forked with parent context + skill prompt
  5. Agent executes, results returned to parent

MCP Skills Bridge

MCP server prompts automatically wrapped as skills. Registered in app state, available to both model and SkillTool. This means any MCP server that exposes prompts gets skill integration for free.

Hook System

Hooks are shell commands triggered by tool lifecycle events:

  • PreToolUse: Runs before a tool executes (can block execution)
  • PostToolUse: Runs after a tool completes
  • Configured in settings.json or plugin hooks.json
  • Variable substitution for dynamic values (tool name, input, etc.)

Design Patterns

  • Plugin Architecture: Isolated component loading with manifest-driven discovery
  • Composite: Skills compose messages + agent execution into reusable workflows
  • Strategy: Different skill types (prompt vs. shell vs. MCP) use different execution strategies
  • Template Method: Frontmatter defines structure, content defines behavior