Initial commit

commands/validate-plugin.md

@@ -0,0 +1,102 @@
+---
+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.