Advanced Plugin Features (2025)

Quick Reference

skills/*/SKILL.md

hooks/hooks.json

.mcp.json

.claude/settings.json

${CLAUDE_PLUGIN_ROOT}

${TOOL_INPUT_*}

Agent Skills

Concept

Skills are dynamically loaded based on task context, enabling:

• Unbounded capacity: Knowledge split across files
• Context efficiency: Only load what's needed
• Progressive disclosure: Three-tier loading

Three-Tier Loading

1. Frontmatter: Loaded at startup (triggers)
2. SKILL.md body: Loaded on activation
3. references/: Loaded when detail needed

Structure

skills/
└── skill-name/
    ├── SKILL.md           # Core content
    ├── references/        # Detailed docs
    │   └── deep-dive.md
    ├── examples/          # Working code
    │   └── example.md
    └── scripts/           # Utilities
        └── tool.sh

SKILL.md Format

---
name: skill-name
description: |
  When to activate this skill. Include:
  (1) Use case 1
  (2) Use case 2
  Provides: what it offers
---

# Skill Title

## Quick Reference
[Tables, key points]

## Core Content
[Essential information - keep lean]

## Additional Resources
See `references/` for detailed guidance.

Hooks

Configuration

Inline in plugin.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh"
      }]
    }]
  }
}

Separate hooks.json:

{
  "PostToolUse": [{
    "matcher": "Write",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
      "timeout": 5000
    }]
  }]
}

Matchers

• Write

  - File writes

• Edit

  - File edits

• Bash

  - Shell commands

• Write|Edit

  - Multiple tools

• .*

  - Any tool (use sparingly)

Common Patterns

Auto-test after changes:

{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh"
    }]
  }]
}

Validate before Bash:

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-cmd.sh"
    }]
  }]
}

MCP Server Integration

Configuration

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

External Services

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp-server"],
      "env": {
        "STRIPE_API_KEY": "${STRIPE_API_KEY}"
      }
    }
  }
}

Repository Configuration

Team Distribution

Create

.claude/settings.json

{
  "extraKnownMarketplaces": [
    "company/internal-plugins"
  ],
  "plugins": {
    "enabled": [
      "deployment-helper@company",
      "code-standards@company"
    ]
  }
}

Workflow

1. Maintainer creates

   .claude/settings.json

2. Team members clone repo
3. Trust folder when prompted
4. Plugins install automatically

Best Practices

Progressive Disclosure

• Keep SKILL.md under 500 lines
• Move details to

  references/

• Use

  examples/

  for working code
• Reference files with relative paths

Hooks

• Use specific matchers (avoid

  .*

  )
• Set reasonable timeouts
• Use

  ${CLAUDE_PLUGIN_ROOT}

  for paths
• Test scripts independently

MCP

• Document required env vars
• Provide setup instructions
• Use environment variables for secrets
• Test connection before distribution

Additional Resources

For detailed patterns, see:

• references/hooks-advanced.md

  - Complete hook patterns

• references/mcp-patterns.md

  - MCP integration examples

• references/team-distribution.md

  - Repository configuration

• examples/hook-scripts.md

  - Working hook scripts