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
-
Frontmatter: Loaded at startup (triggers)
-
SKILL.md body: Loaded on activation
-
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
-
Maintainer creates .claude/settings.json
-
Team members clone repo
-
Trust folder when prompted
-
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