103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
---
|
|
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.
|