🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• ❌ WRONG: D:/repos/project/file.tsx
• ✅ CORRECT: D:\repos\project\file.tsx

This applies to:

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

---

Advanced Plugin Features (2025)

Comprehensive guide to cutting-edge Claude Code plugin capabilities introduced in 2025.

Agent Skills

What are Agent Skills? Skills that Claude autonomously invokes based on task context, enabling dynamic knowledge loading and context-efficient workflows through progressive disclosure architecture.

Key Characteristics (2025)

• Automatic Discovery: Skills are discovered from skills/ directory upon plugin installation
• Context-Driven: Claude loads Skills only when relevant to the current task
• Progressive Disclosure: Three-tier information structure (frontmatter → SKILL.md body → linked files)
• Dynamic Loading: Reduces context usage by loading only necessary components
• Unbounded Capacity: With filesystem access, agents can bundle effectively unlimited content

Creating Agent Skills

Directory Structure:

plugin-root/
└── skills/
    ├── skill-name-1/
    │   └── SKILL.md
    └── skill-name-2/
        ├── SKILL.md
        ├── examples/
        └── resources/

SKILL.md Format:

---
name: skill-name
description: "Complete [domain] system. PROACTIVELY activate for: (1) [use cases]. Provides: [capabilities]."
license: MIT
---

# Skill Title

## Overview
High-level summary always loaded

## Core Concepts
Key information organized for quick scanning

## Examples
Concrete usage patterns

## Best Practices
Proven approaches and patterns

Agent Skills Best Practices (2025)

Evaluation-Driven Development:

• Start by identifying capability gaps through representative tasks
• Observe where agents struggle, then build skills addressing specific shortcomings
• Avoid anticipating needs upfront - respond to actual failures

Structural Scalability:

• When SKILL.md becomes unwieldy, split content into separate files and reference them
• Keep mutually exclusive contexts in distinct paths to reduce token consumption
• Code should serve dual purposes: executable tools AND documentation
• Split large skills into focused components as needed

Iterative Refinement:

• Collaborate with Claude during development
• Ask Claude to capture successful approaches into reusable context
• Request self-reflection on failure modes to reveal actual information needs

DO:

• Use descriptive, action-oriented names
• Write comprehensive activation descriptions with numbered use cases
• Include concrete examples and code snippets
• Organize content with clear headers for scanning
• Keep individual skills focused on single domains

DON'T:

• Create overly broad skills that cover too many topics
• Duplicate content across multiple skills
• Skip the frontmatter metadata
• Use generic descriptions that don't specify activation scenarios

Context Efficiency Strategy (2025)

Agent Skills achieve unbounded capacity through:

1. Progressive Disclosure: Three-tier structure (frontmatter loaded at startup → SKILL.md body when determining relevance → additional files only when needed)
2. Lazy Loading: Only loaded when task matches activation criteria
3. Filesystem Retrieval: With code execution capabilities, agents retrieve only necessary components instead of loading entire skills
4. Focused Scope: Each skill covers specific domain/capability
5. Structured Content: Headers enable Claude to scan efficiently
6. Optimized Metadata: Name and description fields directly influence triggering accuracy

Example Activation Pattern:

User task: "Deploy to production"
→ Claude scans skill metadata (frontmatter only)
→ Identifies deployment-workflows skill as relevant
→ Loads SKILL.md body to confirm match
→ Retrieves only needed sections/files
→ Unloads when task complete

Result: Effectively unlimited bundled content without context window constraints.

Hooks

What are Hooks? Automatic triggers that execute actions at specific events during Claude Code's workflow.

Hook Event Types (2025)

Tool Lifecycle:

• PreToolUse: Before any tool execution (validation, preparation)
• PostToolUse: After tool execution (testing, cleanup, notifications)

Session Lifecycle:

• SessionStart: When Claude Code session begins
• SessionEnd: When session terminates
• PreCompact: Before context compaction (cleanup, state save)

User Interaction:

• UserPromptSubmit: After user submits prompt (logging, preprocessing)
• Notification: When notifications are displayed
• Stop: When user stops execution
• SubagentStop: When subagent terminates

Hook Configuration

Inline in plugin.json:

{
  "name": "my-plugin",
  "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": "./scripts/format.sh",
          "env": {
            "FILE_PATH": "${TOOL_INPUT_FILE_PATH}"
          }
        }
      ]
    }
  ],
  "SessionStart": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Session started at $(date)' >> session.log"
        }
      ]
    }
  ]
}

Hook Matchers

Tool Matchers: Match specific tools using regex patterns:

• Write - File write operations
• Edit - File edit operations
• Write|Edit - Either write or edit
• Bash - Shell command execution
• .* - Any tool (use sparingly)

Matcher Best Practices:

• Be specific to avoid unnecessary executions
• Use | for multiple tools
• Test matchers thoroughly
• Document why each matcher is used

Common Hook Patterns

Automated Testing:

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

Code Formatting:

{
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write ${TOOL_INPUT_FILE_PATH}"
        }
      ]
    }
  ]
}

Session Logging:

{
  "SessionStart": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "${CLAUDE_PLUGIN_ROOT}/scripts/log-session.sh"
        }
      ]
    }
  ]
}

Validation:

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

MCP Server Integration

What is MCP? Model Context Protocol enables Claude to interact with external tools, APIs, and services through standardized server interfaces.

MCP Configuration (2025)

Inline in plugin.json (Recommended for Distribution):

{
  "name": "my-plugin",
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "SERVER_URL": "https://api.example.com"
      }
    },
    "local-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

Separate .mcp.json:

{
  "mcpServers": {
    "database-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/db-server.js"],
      "env": {
        "DB_CONNECTION": "${DATABASE_URL}"
      }
    }
  }
}

MCP Best Practices

DO:

• Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
• Document required environment variables in README
• Provide sensible defaults for optional configuration
• Test MCP servers in isolation before integration
• Include error handling in server implementations

DON'T:

• Hardcode absolute paths (breaks portability)
• Expose secrets in plugin.json (use environment variables)
• Assume environment variables are always set
• Skip validation of MCP server responses

MCP Use Cases

API Integration:

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

Database Access:

{
  "mcpServers": {
    "postgres": {
      "command": "${CLAUDE_PLUGIN_ROOT}/bin/pg-server",
      "args": ["--connection", "${DATABASE_URL}"]
    }
  }
}

Custom Tooling:

{
  "mcpServers": {
    "internal-tools": {
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/tools_server.py"],
      "env": {
        "TOOLS_CONFIG": "${CLAUDE_PLUGIN_ROOT}/config/tools.json"
      }
    }
  }
}

Repository-Level Plugin Configuration

What is it? Automatic marketplace and plugin installation for team members when they trust a repository folder.

Configuration File Location

Create .claude/settings.json at repository root:

repo-root/
├── .claude/
│   └── settings.json
├── src/
└── README.md

Settings Format

{
  "extraKnownMarketplaces": [
    "company-org/internal-plugins",
    "JosiahSiegel/claude-plugin-marketplace"
  ],
  "plugins": {
    "enabled": [
      "deployment-helper@company-org",
      "test-master@JosiahSiegel",
      "code-review-helper"
    ]
  }
}

Team Distribution Workflow

1. Repository Maintainer:

   • Create .claude/settings.json
   • Configure required marketplaces and plugins
   • Commit to version control
   • Document in README that team should trust folder

2. Team Member:

   • Clone repository
   • Open in Claude Code
   • Trust folder when prompted
   • Automatic installation occurs

3. Updates:

   • Maintainer updates settings.json
   • Team members pull changes
   • Claude Code applies updated configuration

Best Practices

Start Minimal:

{
  "extraKnownMarketplaces": ["company/tools"],
  "plugins": {
    "enabled": ["essential-plugin@company"]
  }
}

Document Requirements: Add to README:

## Claude Code Setup

This repository uses Claude Code plugins for standardized workflows.

### First Time Setup
1. Install Claude Code
2. Clone this repository
3. Open in Claude Code
4. Trust this repository folder when prompted

Plugins will be installed automatically.

Security Considerations:

• Only trust repositories from known sources
• Review settings.json before trusting
• Use organizational repositories for internal plugins
• Document why each plugin is required

Environment Variables

Standard Variables (2025)

${CLAUDE_PLUGIN_ROOT}: Resolves to plugin's absolute installation path.

Usage:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "local-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

Why Use It:

• Ensures portability across different installation locations
• Works on all platforms (Windows, Mac, Linux)
• Simplifies plugin distribution
• Enables relative path resolution

Custom Environment Variables

In Hooks:

{
  "hooks": [
    {
      "type": "command",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/deploy.sh",
      "env": {
        "ENVIRONMENT": "${DEPLOY_ENV}",
        "API_KEY": "${API_KEY}",
        "CUSTOM_VAR": "value"
      }
    }
  ]
}

In MCP Servers:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "env": {
        "API_URL": "${COMPANY_API_URL}",
        "AUTH_TOKEN": "${COMPANY_AUTH_TOKEN}"
      }
    }
  }
}

Best Practices:

• Document all required environment variables in README
• Provide .env.example template
• Use sensible defaults when possible
• Validate environment variables in scripts
• Never hardcode secrets

Complete Plugin Example (2025 Best Practices)

deployment-automation/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md
│   └── deploy-production.md
├── agents/
│   └── deployment-expert.md
├── skills/
│   ├── deployment-workflows/
│   │   └── SKILL.md
│   └── kubernetes-patterns/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
├── scripts/
│   ├── validate-deployment.sh
│   └── run-tests.sh
├── .claude/
│   └── settings.json
└── README.md

plugin.json:

{
  "name": "deployment-automation",
  "version": "2.0.0",
  "description": "Complete deployment automation system. PROACTIVELY activate for: (1) ANY deployment task, (2) Production releases, (3) Rollback operations, (4) Deployment validation, (5) Kubernetes workflows. Provides: automated deployment, rollback safety, validation hooks, multi-environment support. Ensures safe, reliable deployments.",
  "author": {
    "name": "Your Company",
    "email": "[email protected]"
  },
  "keywords": ["deployment", "kubernetes", "production", "automation", "cicd"],
  "license": "MIT",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-deployment.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "kubernetes": {
      "command": "kubectl",
      "args": ["proxy"],
      "env": {
        "KUBECONFIG": "${KUBECONFIG}"
      }
    }
  }
}

hooks/hooks.json:

{
  "SessionStart": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Deployment session started' >> deployment.log"
        }
      ]
    }
  ]
}

.claude/settings.json:

{
  "extraKnownMarketplaces": ["company/internal-tools"],
  "plugins": {
    "enabled": ["deployment-automation@company"]
  }
}

Migration from Legacy Plugins

Key Changes in 2025

1. Component Discovery:

• Old: Manual registration in plugin.json
• New: Automatic discovery from standard directories

2. Skills → Agent Skills:

• Old: Static skills loaded in context
• New: Dynamic Agent Skills loaded on-demand

3. Hooks:

• Old: Limited hook support
• New: Comprehensive event system (PreToolUse, PostToolUse, SessionStart, etc.)

4. MCP Integration:

• Old: External configuration required
• New: Inline in plugin.json or .mcp.json

5. Repository Configuration:

• Old: Manual plugin installation per developer
• New: Automatic installation via .claude/settings.json

Migration Checklist

• Update plugin.json to version 2.x.x
• Convert static skills to Agent Skills with proper frontmatter
• Add hooks for automated workflows
• Configure MCP servers inline if applicable
• Create .claude/settings.json for team distribution
• Update README with 2025 installation instructions
• Test on all platforms (Windows, Mac, Linux)
• Use ${CLAUDE_PLUGIN_ROOT} for all internal paths
• Validate with latest Claude Code version

Debugging Advanced Features

Debug Mode

claude --debug

Shows:

• Plugin loading status
• Agent Skills discovery and activation
• Hook registration and execution
• MCP server initialization
• Environment variable resolution

Common Issues

Agent Skills not loading:

• Verify SKILL.md exists in skills/skill-name/ directory
• Check frontmatter has name and description fields
• Ensure description includes activation criteria

Hooks not executing:

• Verify event type is valid (PreToolUse, PostToolUse, etc.)
• Check matcher pattern matches tool name
• Confirm script has execute permissions
• Validate ${CLAUDE_PLUGIN_ROOT} resolves correctly

MCP server not starting:

• Check command and args are correct
• Verify required environment variables are set
• Test MCP server independently
• Review server logs for errors

Repository settings not applying:

• Confirm .claude/settings.json is at repository root
• Verify repository folder is trusted
• Check marketplace names are correct
• Ensure plugins exist in specified marketplaces

Additional Resources

• Official Plugin Reference: https://docs.claude.com/en/docs/claude-code/plugins-reference
• Marketplace Guide: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
• Agent Skills Engineering: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• MCP Documentation: https://docs.claude.com/en/docs/claude-code/mcp
• Community Plugins: https://claudecodemarketplace.com/

Conclusion

2025 plugin features enable:

• Context Efficiency: Agent Skills load knowledge dynamically
• Automation: Hooks trigger workflows automatically
• Integration: MCP connects external tools seamlessly
• Team Standardization: Repository-level configuration ensures consistency

Apply these patterns to create production-ready, scalable plugins that leverage the full power of Claude Code's 2025 capabilities.