advanced-features-2025

name

advanced-features-2025

description

Advanced Claude Code plugin features (2025-2026) — hooks, MCP integration, team distribution, and progressive disclosure. PROACTIVELY activate for: (1) progressive disclosure design (3-level loading: metadata, body, references), (2) hook automation and event-driven plugins, (3) PreToolUse and PostToolUse hooks, (4) MCP server integration, (5) .mcp.json configuration and stdio/sse/http/ws transports, (6) team plugin distribution patterns (project-level, repo-level), (7) repository-level plugin layouts, (8) context efficiency techniques, (9) plugin sharing and private marketplaces, (10) ${CLAUDE_PLUGIN_ROOT} for cross-platform paths. Provides: hooks reference, MCP integration patterns, team distribution playbook, context efficiency tips, and migration guidance from legacy patterns.

Advanced Plugin Features (2025)

Quick Reference

Feature	Location	Purpose
Agent Skills	skills/*/SKILL.md	Dynamic knowledge loading
Hooks	hooks/hooks.json	Event automation
MCP Servers	.mcp.json	External integrations
Team Config	.claude/settings.json	Repository plugins

Hook Event	When Fired	Use Case
PreToolUse	Before tool	Validation
PostToolUse	After tool	Testing, linting
SessionStart	Session begins	Logging, setup
SessionEnd	Session ends	Cleanup
UserPromptSubmit	Prompt submitted	Preprocessing
PreCompact	Before compact	State save
Notification	Notification shown	Custom alerts
Stop	User stops	Cleanup
SubagentStop	Subagent ends	Logging

Variable	Purpose
${CLAUDE_PLUGIN_ROOT}	Plugin installation path
${TOOL_INPUT_*}	Tool input parameters

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 at repo root:

{
  "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