gh-josiahsiegel-claude-code-marketplace-plugins-plugin-master/commands/validate-plugin.md

description

description
Comprehensive validation of plugin structure, manifests, and configuration against 2025 standards

🚨 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

---

Validate Plugin

Systematically validate plugin files against current Claude Code requirements and best practices.

Purpose

Pre-publishing validation that checks plugin.json schema, directory structure, component files, and marketplace compatibility. Identifies errors, warnings, and optimization opportunities.

Instructions

1. Locate plugin - Use current directory or specified path
2. Validate plugin.json (2025 standards):
   • Required field: name
   • Schema validation: author as object, version as string, keywords as array
   • Recommended fields: description, license, homepage, repository
   • Check paths use ${CLAUDE_PLUGIN_ROOT} for portability
   • Verify MCP servers use proper configuration format
3. Check directory structure:
   • .claude-plugin/ contains plugin.json (and optionally .mcp.json)
   • Component directories (commands/, agents/, skills/) at plugin root
   • Files properly named (kebab-case, .md extensions)
   • Hook configuration (hooks/hooks.json or inline in plugin.json)
4. Validate components (2025 features):
   • Commands have frontmatter with description
   • Agents have proper frontmatter with capabilities
   • Agent Skills have SKILL.md with name and description
   • Hooks have valid event types (PreToolUse, PostToolUse, SessionStart, etc.)
   • MCP servers reference valid commands and args
5. Check 2025 best practices:
   • Use of Agent Skills for dynamic knowledge loading
   • Hooks configured for automated workflows
   • Environment variables properly used (${CLAUDE_PLUGIN_ROOT})
   • Repository-level configuration support (.claude/settings.json template)
6. Check marketplace.json if present:
   • Validate owner structure
   • Check plugin entries have required fields
   • Verify source paths are correct (relative paths start with ./)
   • Confirm descriptions and keywords are synchronized
7. Report findings with severity levels and actionable fixes

Validation Checklist

Critical (Must Fix):

• plugin.json exists and has valid JSON
• name field present
• author is object not string
• version is string not number
• keywords is array not string

Warnings (Should Fix):

• Missing recommended fields (description, license)
• Inconsistent naming conventions
• Missing frontmatter in components

Suggestions (Nice to Have):

• Add homepage and repository URLs
• Expand keywords for better discovery
• Add examples to README

Example Usage

/validate-plugin
/validate-plugin in plugins/my-plugin
/validate-plugin before publishing

Returns structured validation report with pass/fail status.