
marketplace-validator-plugin
Comprehensive validation for Claude Code marketplaces and plugins with quality scoring, security scanning, and automated checks
- version
- 1.0.0
- GitHub stars
- 9
Install
/plugin install marketplace-validator-plugin@open-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add dhofheinz/open-plugins.
Contents
Discovered from sourceCommands 39
Operation: Check Categories
Validate category assignment against OpenPlugins standard category list.
Parameters from $ARGUMENTS
- category: Category name to validate (required)
- suggest: Show similar categories if invalid (optional, default: true)
OpenPlugins Standard Categories
OpenPlugins defines exactly 10 approved categories:
- development - Code generation, scaffolding, refactoring
- testing - Test generation, coverage, quality assurance
- deployment - CI/CD, infrastructure, release automation
- documentation - Docs generation, API documentation
- security - Vulnerability scanning, secret detection
- database - Schema design, migrations, queries
- monitoring - Performance analysis, logging
- productivity - Workflow automation, task management
- quality - Linting, formatting, code review
- collaboration - Team tools, communication
Category Selection Guidance
development:
- Code generators
- Project scaffolding
- Refactoring tools
- Boilerplate generation
testing:
- Test generators
- Test runners
- Coverage tools
- QA automation
deployment:
- CI/CD pipelines
- Infrastructure as code
- Release automation
- Environment management
documentation:
- README generators
- API doc generation
- Changelog automation
- Architecture diagrams
security:
- Secret scanning
- Vulnerability detection
- Security audits
- Compliance checking
database:
- Schema design
- Migration tools
- Query builders
- Database testing
monitoring:
- Performance profiling
- Log analysis
- Metrics collection
- Alert systems
productivity:
- Task automation
- Workflow orchestration
- Time management
- Note-taking
quality:
- Linters
- Code formatters
- Code review tools
- Complexity analysis
collaboration:
- Team communication
- Code review
- Knowledge sharing
- Project management
Workflow
-
Extract Category from Arguments
Parse $ARGUMENTS to extract category parameter If category not provided, return error Normalize to lowercase -
Execute Category Validator
Execute .scripts/category-validator.sh "$category" Exit codes: - 0: Valid category - 1: Invalid category - 2: Missing required parameters -
Check Against Approved List
Compare category against 10 approved categories Use exact string matching (case-insensitive) -
Suggest Alternatives (if invalid)
IF category invalid AND suggest:true: Calculate similarity scores Suggest closest matching categories Show category descriptions -
Return Validation Report
Format results: - Status: PASS/FAIL - Category: <provided-category> - Valid: yes/no - Description: <category-description> (if valid) - Suggestions: <list> (if invalid) - Score impact: +5 points (if valid)
Examples
# Valid category
/best-practices categories category:development
# Result: PASS - Valid OpenPlugins category
# Invalid category (typo)
/best-practices categories category:developement
# Result: FAIL - Did you mean: development?
# Invalid category (plural)
/best-practices categories category:tests
# Result: FAIL - Did you mean: testing?
# Invalid category (custom)
/best-practices categories category:utilities
# Result: FAIL - Not in approved list
# Suggestions: productivity, quality, development
# Case insensitive
/best-practices categories category:TESTING
# Result: PASS - Valid (normalized to: testing)
Error Handling
Missing category parameter:
ERROR: Missing required parameter 'category'
Usage: /best-practices categories category:<category-name>
Example: /best-practices categories category:development
Empty category:
ERROR: Category cannot be empty
Choose from 10 approved OpenPlugins categories:
development, testing, deployment, documentation, security,
database, monitoring, productivity, quality, collaboration
Output Format
Success (Valid Category):
✅ Category Validation: PASS
Category: development
Valid: Yes
Description: Code generation, scaffolding, refactoring
Use Cases:
- Code generators
- Project scaffolding tools
- Refactoring utilities
- Boilerplate generation
Quality Score Impact: +5 points
The category is approved for OpenPlugins marketplace.
Failure (Invalid Category):
❌ Category Validation: FAIL
Category: developement
Valid: No
This category is not in the OpenPlugins approved list.
Did you mean?
1. development - Code generation, scaffolding, refactoring
2. deployment - CI/CD, infrastructure, release automation
All Approved Categories:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. development - Code generation, scaffolding
2. testing - Test generation, coverage
3. deployment - CI/CD, infrastructure
4. documentation - Docs generation, API docs
5. security - Vulnerability scanning
6. database - Schema design, migrations
7. monitoring - Performance analysis
8. productivity - Workflow automation
9. quality - Linting, formatting
10. collaboration - Team tools, communication
Quality Score Impact: 0 points (fix to gain +5)
Choose the most appropriate category from the approved list.
Failure (Multiple Matches):
❌ Category Validation: FAIL
Category: code-tools
Valid: No
This category is not approved. Consider these alternatives:
Best Matches:
1. development - Code generation, scaffolding, refactoring
2. quality - Linting, formatting, code review
3. productivity - Workflow automation, task management
Which fits your plugin best?
- If generating/scaffolding code → development
- If analyzing/formatting code → quality
- If automating workflows → productivity
Quality Score Impact: 0 points (fix to gain +5)
Category Decision Tree
Use this to select the right category:
Does your plugin...
Generate or scaffold code?
→ development
Run tests or check quality?
→ testing (if running tests)
→ quality (if analyzing/formatting code)
Deploy or manage infrastructure?
→ deployment
Generate documentation?
→ documentation
Scan for security issues?
→ security
Work with databases?
→ database
Monitor performance or logs?
→ monitoring
Automate workflows or tasks?
→ productivity
Improve code quality?
→ quality
Facilitate team collaboration?
→ collaboration
Common Mistakes
Using plural forms:
- ❌
tests→ ✅testing - ❌
deployments→ ✅deployment - ❌
databases→ ✅database
Using generic terms:
- ❌
tools→ Choose specific category - ❌
utilities→ Choose specific category - ❌
helpers→ Choose specific category
Using multiple categories:
- ❌
development,testing→ Choose ONE primary category - Use keywords for additional topics
Using custom categories:
- ❌
api-tools→ ✅developmentorproductivity - ❌
devops→ ✅deployment - ❌
ci-cd→ ✅deployment
Compliance Criteria
PASS Requirements:
- Exact match with one of 10 approved categories
- Case-insensitive matching accepted
- Single category only (not multiple)
FAIL Indicators:
- Not in approved list
- Plural forms
- Custom categories
- Multiple categories
- Empty or missing
Request: $ARGUMENTS
Operation: Check Naming Conventions
Validate plugin names against OpenPlugins lowercase-hyphen naming convention.
Parameters from $ARGUMENTS
- name: Plugin name to validate (required)
- fix: Auto-suggest corrected name (optional, default: true)
OpenPlugins Naming Convention
Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
Valid Examples:
code-formattertest-runnerdeploy-automationapi-clientdatabase-migration
Invalid Examples:
Code-Formatter(uppercase)test_runner(underscore)Deploy Automation(space)APIClient(camelCase)-helper(leading hyphen)tool-(trailing hyphen)
Workflow
-
Extract Name from Arguments
Parse $ARGUMENTS to extract name parameter If name not provided, return error -
Execute Naming Validator
Execute .scripts/naming-validator.sh "$name" Exit codes: - 0: Valid naming convention - 1: Invalid naming convention - 2: Missing required parameters -
Process Results
IF valid: Return success with confirmation ELSE: Return failure with specific violations Suggest corrected name if fix:true Provide examples -
Return Compliance Report
Format results: - Status: PASS/FAIL - Name: <provided-name> - Valid: yes/no - Issues: <list of violations> - Suggestion: <corrected-name> - Score impact: +5 points (if valid)
Examples
# Valid name
/best-practices naming name:my-awesome-plugin
# Result: PASS - Valid lowercase-hyphen format
# Invalid name with uppercase
/best-practices naming name:MyPlugin
# Result: FAIL - Contains uppercase (M, P)
# Suggestion: my-plugin
# Invalid name with underscore
/best-practices naming name:test_runner
# Result: FAIL - Contains underscore (_)
# Suggestion: test-runner
# Invalid name with space
/best-practices naming name:"Test Runner"
# Result: FAIL - Contains space
# Suggestion: test-runner
Error Handling
Missing name parameter:
ERROR: Missing required parameter 'name'
Usage: /best-practices naming name:<plugin-name>
Example: /best-practices naming name:my-plugin
Empty name:
ERROR: Name cannot be empty
Provide a valid plugin name following lowercase-hyphen convention.
Output Format
Success (Valid Name):
✅ Naming Convention: PASS
Name: code-formatter
Format: lowercase-hyphen
Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
Valid: Yes
Quality Score Impact: +5 points
The name follows OpenPlugins naming conventions perfectly.
Failure (Invalid Name):
❌ Naming Convention: FAIL
Name: Code_Formatter
Format: Invalid
Valid: No
Issues Found:
1. Contains uppercase characters: C, F
2. Contains underscores instead of hyphens
Suggested Correction: code-formatter
Quality Score Impact: 0 points (fix to gain +5)
Fix these issues to comply with OpenPlugins standards.
Compliance Criteria
PASS Requirements:
- All lowercase letters (a-z)
- Numbers allowed (0-9)
- Hyphens for word separation
- No leading or trailing hyphens
- No consecutive hyphens
- No other special characters
- Descriptive (not generic like "plugin" or "tool")
FAIL Indicators:
- Uppercase letters
- Underscores, spaces, or special characters
- Leading/trailing hyphens
- Empty or single character names
- Generic non-descriptive names
Best Practices Guidance
Good Names:
- Describe functionality:
code-formatter,test-runner - Include technology:
python-linter,docker-manager - Indicate purpose:
api-client,database-migrator
Avoid:
- Generic:
plugin,tool,helper,utility - Abbreviations only:
fmt,tst,db - Version numbers:
plugin-v2,tool-2024
Request: $ARGUMENTS
Operation: Full Standards Compliance
Execute comprehensive OpenPlugins and Claude Code best practices validation with complete compliance reporting.
Parameters from $ARGUMENTS
- path: Path to plugin or marketplace directory (required)
- fix: Auto-suggest corrections for all issues (optional, default: true)
- format: Output format (text|json|markdown) (optional, default: text)
Complete Standards Check
This operation validates all four best practice categories:
- Naming Convention - Lowercase-hyphen format
- Semantic Versioning - MAJOR.MINOR.PATCH format
- Category Assignment - One of 10 approved categories
- Keyword Quality - 3-7 relevant, non-generic keywords
Workflow
-
Detect Target Type
Parse $ARGUMENTS to extract path parameter Detect if path is plugin or marketplace: - Plugin: Has plugin.json - Marketplace: Has .claude-plugin/marketplace.json -
Load Metadata
IF plugin: Read plugin.json Extract: name, version, keywords, category ELSE IF marketplace: Read .claude-plugin/marketplace.json Extract marketplace metadata Validate each plugin entry ELSE: Return error: Invalid target -
Execute All Validations
Run in parallel or sequence: A. Naming Validation Execute check-naming.md with name parameter Store result B. Version Validation Execute validate-versioning.md with version parameter Store result C. Category Validation Execute check-categories.md with category parameter Store result D. Keyword Validation Execute validate-keywords.md with keywords parameter Store result -
Aggregate Results
Collect all validation results: - Individual pass/fail status - Specific issues found - Suggested corrections - Score impact for each Calculate overall compliance: - Total score: Sum of individual scores - Pass count: Number of passing validations - Fail count: Number of failing validations - Compliance percentage: (pass / total) × 100 -
Generate Compliance Report
Create comprehensive report: - Executive summary - Individual validation details - Issue prioritization - Suggested fixes - Compliance score - Publication readiness -
Return Results
Format according to output format: - text: Human-readable console output - json: Machine-parseable JSON - markdown: Documentation-ready markdown
Examples
# Full compliance check on current directory
/best-practices full-standards path:.
# Check specific plugin with JSON output
/best-practices full-standards path:./my-plugin format:json
# Check with auto-fix suggestions
/best-practices full-standards path:. fix:true
# Marketplace validation
/best-practices full-standards path:./marketplace
Error Handling
Missing path parameter:
ERROR: Missing required parameter 'path'
Usage: /best-practices full-standards path:<directory>
Examples:
/best-practices full-standards path:.
/best-practices full-standards path:./my-plugin
Invalid path:
ERROR: Invalid path or not a plugin/marketplace
Path: <provided-path>
The path must contain either:
- plugin.json (for plugins)
- .claude-plugin/marketplace.json (for marketplaces)
Check the path and try again.
Missing metadata file:
ERROR: Metadata file not found
Expected one of:
- plugin.json
- .claude-plugin/marketplace.json
This does not appear to be a valid Claude Code plugin or marketplace.
Output Format
Text Format (Complete Compliance):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPENPLUGINS BEST PRACTICES COMPLIANCE REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: code-formatter-plugin
Type: Plugin
Date: 2024-10-13
Overall Compliance: 100% ✅
Status: PUBLICATION READY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Naming Convention: ✅ PASS
Name: code-formatter
Format: lowercase-hyphen
Score: +5 points
The name follows OpenPlugins naming conventions perfectly.
2. Semantic Versioning: ✅ PASS
Version: 1.2.3
Format: MAJOR.MINOR.PATCH
Score: +5 points
Valid semantic version compliant with semver 2.0.0.
3. Category Assignment: ✅ PASS
Category: quality
Description: Linting, formatting, code review
Score: +5 points
Category is approved and appropriate for this plugin.
4. Keyword Quality: ✅ PASS
Keywords: formatting, javascript, eslint, code-quality, automation
Count: 5 (optimal)
Quality: 10/10
Score: +10 points
Excellent keyword selection with balanced mix.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPLIANCE SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Validations Passed: 4/4 (100%)
Quality Score: 25/25 points
Scoring Breakdown:
✅ Naming Convention: +5 points
✅ Semantic Versioning: +5 points
✅ Category Assignment: +5 points
✅ Keyword Quality: +10 points
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Score: 25/25 points
Publication Status: ✅ READY FOR SUBMISSION
This plugin meets all OpenPlugins best practice standards
and is ready for marketplace submission!
Next Steps:
1. Submit to OpenPlugins marketplace
2. Follow contribution guidelines in CONTRIBUTING.md
3. Open pull request with plugin entry
Text Format (Partial Compliance):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OPENPLUGINS BEST PRACTICES COMPLIANCE REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: Test_Runner
Type: Plugin
Date: 2024-10-13
Overall Compliance: 50% ⚠️
Status: NEEDS IMPROVEMENT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Naming Convention: ❌ FAIL
Name: Test_Runner
Format: Invalid
Score: 0 points
Issues Found:
- Contains uppercase characters: T, R
- Contains underscore instead of hyphen
✏️ Suggested Fix: test-runner
Impact: +5 points (if fixed)
2. Semantic Versioning: ✅ PASS
Version: 1.0.0
Format: MAJOR.MINOR.PATCH
Score: +5 points
Valid semantic version compliant with semver 2.0.0.
3. Category Assignment: ❌ FAIL
Category: test-tools
Valid: No
Score: 0 points
This category is not in the approved list.
✏️ Suggested Fix: testing
Description: Test generation, coverage, quality assurance
Impact: +5 points (if fixed)
4. Keyword Quality: ⚠️ WARNING
Keywords: plugin, tool, awesome
Count: 3 (minimum met)
Quality: 2/10
Score: 2 points
Issues Found:
- Generic terms: plugin, tool
- Marketing terms: awesome
- No functional keywords
✏️ Suggested Fix: testing, automation, pytest, unit-testing, tdd
Impact: +8 points (if improved to excellent)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPLIANCE SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Validations Passed: 1/4 (25%)
Quality Score: 7/25 points
Scoring Breakdown:
❌ Naming Convention: 0/5 points
✅ Semantic Versioning: 5/5 points
❌ Category Assignment: 0/5 points
⚠️ Keyword Quality: 2/10 points
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Score: 7/25 points
Publication Status: ⚠️ NOT READY - NEEDS FIXES
Priority Fixes Required:
1. [P0] Fix naming convention: Test_Runner → test-runner
2. [P0] Fix category: test-tools → testing
3. [P1] Improve keywords: Remove generic terms, add functional keywords
After Fixes (Estimated Score):
✅ Naming Convention: +5 points
✅ Semantic Versioning: +5 points
✅ Category Assignment: +5 points
✅ Keyword Quality: +10 points
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Potential Score: 25/25 points
Next Steps:
1. Apply suggested fixes above
2. Re-run validation: /best-practices full-standards path:.
3. Ensure score reaches 25/25 before submission
JSON Format:
{
"target": "code-formatter",
"type": "plugin",
"timestamp": "2024-10-13T10:00:00Z",
"compliance": {
"overall": 100,
"status": "READY",
"passed": 4,
"failed": 0,
"warnings": 0
},
"validations": {
"naming": {
"status": "pass",
"name": "code-formatter",
"format": "lowercase-hyphen",
"score": 5,
"issues": []
},
"versioning": {
"status": "pass",
"version": "1.2.3",
"format": "MAJOR.MINOR.PATCH",
"score": 5,
"issues": []
},
"category": {
"status": "pass",
"category": "quality",
"valid": true,
"score": 5,
"issues": []
},
"keywords": {
"status": "pass",
"keywords": ["formatting", "javascript", "eslint", "code-quality", "automation"],
"count": 5,
"quality": 10,
"score": 10,
"issues": []
}
},
"score": {
"total": 25,
"maximum": 25,
"percentage": 100,
"breakdown": {
"naming": 5,
"versioning": 5,
"category": 5,
"keywords": 10
}
},
"publication_ready": true,
"next_steps": [
"Submit to OpenPlugins marketplace",
"Follow contribution guidelines",
"Open pull request"
]
}
Markdown Format (for documentation):
# OpenPlugins Best Practices Compliance Report
**Target**: code-formatter
**Type**: Plugin
**Date**: 2024-10-13
**Status**: ✅ PUBLICATION READY
## Overall Compliance
- **Score**: 25/25 points (100%)
- **Validations Passed**: 4/4
- **Publication Ready**: Yes
## Validation Results
### 1. Naming Convention ✅
- **Status**: PASS
- **Name**: code-formatter
- **Format**: lowercase-hyphen
- **Score**: +5 points
The name follows OpenPlugins naming conventions perfectly.
### 2. Semantic Versioning ✅
- **Status**: PASS
- **Version**: 1.2.3
- **Format**: MAJOR.MINOR.PATCH
- **Score**: +5 points
Valid semantic version compliant with semver 2.0.0.
### 3. Category Assignment ✅
- **Status**: PASS
- **Category**: quality
- **Description**: Linting, formatting, code review
- **Score**: +5 points
Category is approved and appropriate for this plugin.
### 4. Keyword Quality ✅
- **Status**: PASS
- **Keywords**: formatting, javascript, eslint, code-quality, automation
- **Count**: 5 (optimal)
- **Quality**: 10/10
- **Score**: +10 points
Excellent keyword selection with balanced mix.
## Score Breakdown
| Validation | Score | Status |
|------------|-------|--------|
| Naming Convention | 5/5 | ✅ Pass |
| Semantic Versioning | 5/5 | ✅ Pass |
| Category Assignment | 5/5 | ✅ Pass |
| Keyword Quality | 10/10 | ✅ Pass |
| **Total** | **25/25** | **✅ Ready** |
## Next Steps
1. Submit to OpenPlugins marketplace
2. Follow contribution guidelines in CONTRIBUTING.md
3. Open pull request with plugin entry
---
*Report generated by marketplace-validator-plugin v1.0.0*
Compliance Scoring
Total Score Breakdown:
- Naming Convention: 5 points
- Semantic Versioning: 5 points
- Category Assignment: 5 points
- Keyword Quality: 10 points
- Maximum Total: 25 points
Publication Readiness:
- 25/25 points (100%): ✅ READY - Perfect compliance
- 20-24 points (80-96%): ✅ READY - Minor improvements optional
- 15-19 points (60-76%): ⚠️ NEEDS WORK - Address issues before submission
- 10-14 points (40-56%): ❌ NOT READY - Significant fixes required
- 0-9 points (0-36%): ❌ NOT READY - Major compliance issues
Integration with Quality Analysis
This operation feeds into the overall quality scoring system:
Best Practices Score (25 points max)
↓
Quality Analysis (calculate-score)
↓
Overall Quality Score (100 points total)
↓
Publication Readiness Determination
Best Practices Workflow
For complete plugin validation:
# 1. Run full standards compliance
/best-practices full-standards path:.
# 2. If issues found, fix them, then re-run
# ... apply fixes ...
/best-practices full-standards path:.
# 3. Once compliant, run comprehensive validation
/validation-orchestrator comprehensive path:.
# 4. Review quality report
# Quality score includes best practices (25 points)
Request: $ARGUMENTS
You are the Best Practices coordinator, ensuring adherence to OpenPlugins and Claude Code standards.
Your Mission
Parse $ARGUMENTS to determine the requested best practices validation operation and route to the appropriate sub-command.
Available Operations
Parse the first word of $ARGUMENTS to determine which operation to execute:
- naming → Read
.claude/commands/best-practices/check-naming.md - versioning → Read
.claude/commands/best-practices/validate-versioning.md - categories → Read
.claude/commands/best-practices/check-categories.md - keywords → Read
.claude/commands/best-practices/validate-keywords.md - full-standards → Read
.claude/commands/best-practices/full-compliance.md
Argument Format
/best-practices <operation> [parameters]
Examples
# Check naming conventions
/best-practices naming name:my-plugin-name
# Validate semantic versioning
/best-practices versioning version:1.2.3
# Check category validity
/best-practices categories category:development
# Validate keywords
/best-practices keywords keywords:"testing,automation,ci-cd"
# Run complete standards compliance check
/best-practices full-standards path:.
OpenPlugins Standards
Naming Convention:
- Format: lowercase-hyphen (e.g.,
code-formatter,test-runner) - Pattern:
^[a-z0-9]+(-[a-z0-9]+)*$ - No underscores, spaces, or uppercase
- Descriptive, not generic (avoid: "plugin", "tool", "helper")
Semantic Versioning:
- Format: MAJOR.MINOR.PATCH (e.g., 1.2.3)
- Pattern:
^[0-9]+\.[0-9]+\.[0-9]+$ - Optional pre-release:
-alpha.1,-beta.2 - Optional build metadata:
+20241013
Categories (choose ONE):
- development - Code generation, scaffolding, refactoring
- testing - Test generation, coverage, quality assurance
- deployment - CI/CD, infrastructure, release automation
- documentation - Docs generation, API documentation
- security - Vulnerability scanning, secret detection
- database - Schema design, migrations, queries
- monitoring - Performance analysis, logging
- productivity - Workflow automation, task management
- quality - Linting, formatting, code review
- collaboration - Team tools, communication
Keywords:
- Count: 3-7 keywords
- Relevance: Functionality, technology, or use-case based
- Avoid: Generic terms (plugin, tool, utility), category duplication
- Good:
testing,automation,python,ci-cd,docker - Bad:
best,awesome,perfect,plugin
Compliance Scoring
Best practices contribute to quality score:
- Valid naming: +5 points
- Semantic versioning: +5 points
- Valid category: +5 points
- Quality keywords (3-7): +10 points
Error Handling
If the operation is not recognized:
- List all available operations
- Show OpenPlugins standards
- Provide compliance guidance
Base Directory
Base directory for this skill: .claude/commands/best-practices/
Your Task
- Parse
$ARGUMENTSto extract operation and parameters - Read the corresponding operation file
- Execute best practices validation
- Return compliance results with specific corrections
Current Request: $ARGUMENTS
Operation: Validate Keywords
Validate keyword selection for relevance, count, and quality against OpenPlugins standards.
Parameters from $ARGUMENTS
- keywords: Comma-separated keyword list (required)
- min: Minimum keyword count (optional, default: 3)
- max: Maximum keyword count (optional, default: 7)
- context: Plugin context for relevance checking (optional, JSON or description)
OpenPlugins Keyword Standards
Count Requirements:
- Minimum: 3 keywords
- Maximum: 7 keywords
- Optimal: 5-6 keywords
Quality Requirements:
- Relevant to plugin functionality
- Searchable terms users would use
- Mix of functionality, technology, and use-case
- No generic marketing terms
- No duplicate category names
Keyword Categories
Functionality Keywords (what it does):
testing,deployment,formatting,linting,migrationgeneration,automation,analysis,monitoring,scanning
Technology Keywords (what it works with):
python,javascript,docker,kubernetes,postgresqlreact,vue,typescript,bash,terraform
Use-Case Keywords (how it's used):
ci-cd,code-review,api-testing,performancetdd,bdd,refactoring,debugging,profiling
Good Keywords Examples
Well-balanced sets:
["testing", "pytest", "automation", "tdd", "python"]["deployment", "kubernetes", "ci-cd", "docker", "helm"]["linting", "javascript", "eslint", "code-quality", "automation"]["database", "postgresql", "migration", "schema", "sql"]
Poor keyword sets:
["plugin", "tool", "awesome"]- Generic/marketing terms["test", "testing", "tester", "tests"]- Redundant variations["development"]- Only category name, too few["a", "b", "c", "d", "e", "f", "g", "h"]- Too many, non-descriptive
Workflow
-
Extract Keywords from Arguments
Parse $ARGUMENTS to extract keywords parameter Split by comma, trim whitespace Normalize to lowercase Remove duplicates -
Execute Keyword Analyzer
Execute .scripts/keyword-analyzer.py "$keywords" "$min" "$max" "$context" Exit codes: - 0: Valid keyword set - 1: Count violation (too few or too many) - 2: Quality issues (generic terms, duplicates) - 3: Missing required parameters -
Validate Count
count = number of keywords IF count < min: FAIL (too few) IF count > max: FAIL (too many) -
Check for Generic Terms
Generic blocklist: - plugin, tool, utility, helper, awesome - best, perfect, great, super, amazing - code, software, app, program Flag any generic terms found -
Analyze Quality
Check for: - Duplicate category names - Redundant variations (test, testing, tests) - Single-character keywords - Non-descriptive terms -
Calculate Relevance Score
Base score: 10 points Deductions: - Generic term: -2 per term - Too few keywords: -5 - Too many keywords: -3 - Redundant variations: -2 per redundancy - Non-descriptive: -1 per term Final score: max(0, base - deductions) -
Return Analysis Report
Format results: - Status: PASS/FAIL/WARNING - Count: <number> (valid range: min-max) - Quality: <score>/10 - Issues: <list of problems> - Suggestions: <improved keyword set> - Score impact: +10 points (if excellent), +5 (if good)
Examples
# Valid keyword set
/best-practices keywords keywords:"testing,pytest,automation,tdd,python"
# Result: PASS - 5 keywords, well-balanced, relevant
# Too few keywords
/best-practices keywords keywords:"testing,python"
# Result: FAIL - Only 2 keywords (minimum: 3)
# Too many keywords
/best-practices keywords keywords:"a,b,c,d,e,f,g,h,i,j"
# Result: FAIL - 10 keywords (maximum: 7)
# Generic terms
/best-practices keywords keywords:"plugin,tool,awesome,best"
# Result: FAIL - Contains generic/marketing terms
# With custom range
/best-practices keywords keywords:"ci,cd,docker" min:2 max:5
# Result: PASS - 3 keywords within custom range
Error Handling
Missing keywords parameter:
ERROR: Missing required parameter 'keywords'
Usage: /best-practices keywords keywords:"keyword1,keyword2,keyword3"
Example: /best-practices keywords keywords:"testing,automation,python"
Empty keywords:
ERROR: Keywords cannot be empty
Provide 3-7 relevant keywords describing your plugin.
Good examples:
- "testing,pytest,automation"
- "deployment,kubernetes,ci-cd"
- "linting,javascript,code-quality"
Output Format
Success (Excellent Keywords):
✅ Keyword Validation: PASS
Keywords: testing, pytest, automation, tdd, python
Count: 5 (optimal range: 3-7)
Quality Score: 10/10
Analysis:
✅ Balanced mix of functionality, technology, and use-case
✅ All keywords relevant and searchable
✅ No generic or marketing terms
✅ Good variety without redundancy
Breakdown:
- Functionality: testing, automation, tdd
- Technology: pytest, python
- Use-case: tdd
Quality Score Impact: +10 points
Excellent keyword selection for discoverability!
Failure (Count Violation):
❌ Keyword Validation: FAIL
Keywords: testing, python
Count: 2 (required: 3-7)
Quality Score: 5/10
Issues Found:
1. Too few keywords (2 < 3 minimum)
2. Missing technology or use-case keywords
Suggestions to improve:
Add 1-3 more relevant keywords such as:
- Functionality: automation, unit-testing
- Use-case: tdd, ci-cd
- Specific tools: pytest, unittest
Recommended: testing, python, pytest, automation, tdd
Quality Score Impact: 0 points (fix to gain +10)
Failure (Generic Terms):
❌ Keyword Validation: FAIL
Keywords: plugin, tool, awesome, best, helper
Count: 5 (valid range)
Quality Score: 2/10
Issues Found:
1. Generic terms detected: plugin, tool, helper
2. Marketing terms detected: awesome, best
3. No functional or technical keywords
These keywords don't help users find your plugin.
Better alternatives:
Instead of generic terms, describe WHAT it does:
- Replace "plugin" → testing, deployment, formatting
- Replace "tool" → specific functionality
- Replace "awesome/best" → actual features
Suggested keywords based on common patterns:
- testing, automation, ci-cd, docker, python
- deployment, kubernetes, infrastructure, terraform
- linting, formatting, code-quality, javascript
Quality Score Impact: 0 points (fix to gain +10)
Warning (Minor Issues):
⚠️ Keyword Validation: WARNING
Keywords: testing, tests, test, automation, ci-cd
Count: 5 (valid range)
Quality Score: 7/10
Issues Found:
1. Redundant variations: testing, tests, test
2. Consider consolidating to single term
Suggestions:
- Keep: testing, automation, ci-cd
- Remove: tests, test (redundant)
- Add: 2 more specific keywords (e.g., pytest, junit)
Recommended: testing, automation, ci-cd, pytest, unit-testing
Quality Score Impact: +7 points (good, but could be better)
Your keywords are functional but could be more diverse.
Keyword Quality Checklist
PASS Requirements:
- 3-7 keywords total
- No generic terms (plugin, tool, utility, helper)
- No marketing terms (awesome, best, perfect)
- No redundant variations
- Mix of functionality and technology
- Relevant to plugin purpose
- Searchable by target users
FAIL Indicators:
- < 3 or > 7 keywords
- Contains generic terms
- Contains marketing fluff
- All keywords same type (only technologies, only functionality)
- Single-character keywords
- Category name duplication
Best Practices
Do:
- Use specific functionality terms
- Include primary technologies
- Add relevant use-cases
- Think about user search intent
- Balance breadth and specificity
Don't:
- Use generic words (plugin, tool, utility)
- Add marketing terms (best, awesome, perfect)
- Duplicate category names exactly
- Use redundant variations
- Add irrelevant technologies
- Use abbreviations without context
Quality Scoring Matrix
10/10 - Excellent:
- 5-6 keywords
- Perfect mix of functionality/technology/use-case
- All highly relevant
- Great search discoverability
7-9/10 - Good:
- 3-7 keywords
- Good mix with minor issues
- Mostly relevant
- Decent discoverability
4-6/10 - Fair:
- Count issues OR some generic terms
- Imbalanced mix
- Partial relevance
- Limited discoverability
0-3/10 - Poor:
- Severe count violations OR mostly generic
- No functional keywords
- Poor relevance
- Very poor discoverability
Request: $ARGUMENTS
Operation: Validate Versioning
Validate version strings against Semantic Versioning 2.0.0 specification.
Parameters from $ARGUMENTS
- version: Version string to validate (required)
- strict: Enforce strict semver (no pre-release/build metadata) (optional, default: false)
Semantic Versioning Standard
Base Pattern: MAJOR.MINOR.PATCH (e.g., 1.2.3)
Strict Format: ^[0-9]+\.[0-9]+\.[0-9]+$
Extended Format (with pre-release and build metadata):
- Pre-release:
1.2.3-alpha.1,2.0.0-beta.2,1.0.0-rc.1 - Build metadata:
1.2.3+20241013,1.0.0+build.1 - Combined:
1.2.3-alpha.1+build.20241013
Valid Examples
Strict Semver (OpenPlugins recommended):
1.0.0- Initial release1.2.3- Standard version2.5.13- Double-digit components0.1.0- Pre-1.0 development
Extended Semver (allowed):
1.0.0-alpha- Alpha release1.0.0-beta.2- Beta release1.0.0-rc.1- Release candidate1.2.3+20241013- With build metadata
Invalid Examples
1.0- Missing PATCHv1.0.0- Leading 'v' prefix1.0.0.0- Too many components1.2.x- Placeholder valueslatest- Non-numeric1.0.0-SNAPSHOT- Non-standard identifier
Workflow
-
Extract Version from Arguments
Parse $ARGUMENTS to extract version parameter If version not provided, return error -
Execute Semantic Version Checker
Execute .scripts/semver-checker.py "$version" "$strict" Exit codes: - 0: Valid semantic version - 1: Invalid format - 2: Missing required parameters - 3: Strict mode violation (valid semver, but has pre-release/build) -
Parse Version Components
Extract components: - MAJOR: Breaking changes - MINOR: Backward-compatible features - PATCH: Backward-compatible fixes - Pre-release: Optional identifier (alpha, beta, rc) - Build metadata: Optional metadata -
Return Validation Report
Format results: - Status: PASS/FAIL/WARNING - Version: <provided-version> - Valid: yes/no - Components: MAJOR.MINOR.PATCH breakdown - Pre-release: <identifier> (if present) - Build: <metadata> (if present) - Score impact: +5 points (if valid)
Examples
# Valid strict semver
/best-practices versioning version:1.2.3
# Result: PASS - Valid semantic version (1.2.3)
# Valid with pre-release
/best-practices versioning version:1.0.0-alpha.1
# Result: PASS - Valid semantic version with pre-release
# Invalid format
/best-practices versioning version:1.0
# Result: FAIL - Missing PATCH component
# Strict mode with pre-release
/best-practices versioning version:1.0.0-beta strict:true
# Result: WARNING - Valid semver but not strict format
# Invalid prefix
/best-practices versioning version:v1.2.3
# Result: FAIL - Contains 'v' prefix (use 1.2.3)
Error Handling
Missing version parameter:
ERROR: Missing required parameter 'version'
Usage: /best-practices versioning version:<semver>
Example: /best-practices versioning version:1.2.3
Invalid format:
ERROR: Invalid semantic version format
The version must follow MAJOR.MINOR.PATCH format.
Examples:
- 1.0.0 (initial release)
- 1.2.3 (standard version)
- 2.0.0-beta.1 (pre-release)
Output Format
Success (Valid Semver):
✅ Semantic Versioning: PASS
Version: 1.2.3
Format: MAJOR.MINOR.PATCH
Valid: Yes
Components:
- MAJOR: 1 (breaking changes)
- MINOR: 2 (new features)
- PATCH: 3 (bug fixes)
Quality Score Impact: +5 points
The version follows Semantic Versioning 2.0.0 specification.
Success with Pre-release:
✅ Semantic Versioning: PASS
Version: 1.0.0-beta.2
Format: MAJOR.MINOR.PATCH-PRERELEASE
Valid: Yes
Components:
- MAJOR: 1
- MINOR: 0
- PATCH: 0
- Pre-release: beta.2
Quality Score Impact: +5 points
Note: Pre-release versions indicate unstable releases.
Failure (Invalid Format):
❌ Semantic Versioning: FAIL
Version: 1.0
Format: Invalid
Valid: No
Issues Found:
1. Missing PATCH component
2. Expected format: MAJOR.MINOR.PATCH
Suggested Correction: 1.0.0
Quality Score Impact: 0 points (fix to gain +5)
Fix to comply with Semantic Versioning 2.0.0 specification.
Reference: https://semver.org/
Warning (Strict Mode):
⚠️ Semantic Versioning: WARNING
Version: 1.0.0-alpha.1
Format: Valid semver, but not strict
Valid: Yes (with pre-release)
Note: OpenPlugins recommends strict MAJOR.MINOR.PATCH format
without pre-release or build metadata for marketplace submissions.
Recommended: 1.0.0 (for stable release)
Quality Score Impact: +5 points (valid, but consider strict format)
Versioning Guidelines
When to increment:
MAJOR (X.0.0):
- Breaking API changes
- Incompatible changes
- Major rewrites
MINOR (x.Y.0):
- New features (backward-compatible)
- Deprecations
- Significant improvements
PATCH (x.y.Z):
- Bug fixes
- Security patches
- Minor improvements
Initial Development:
- Start with
0.1.0 - Increment MINOR for features
- First stable release:
1.0.0
Pre-release Identifiers:
alpha- Early testingbeta- Feature complete, testingrc- Release candidate
Compliance Criteria
PASS Requirements:
- Three numeric components (MAJOR.MINOR.PATCH)
- Each component is non-negative integer
- Components separated by dots
- Optional pre-release identifier (hyphen-separated)
- Optional build metadata (plus-separated)
- No leading zeros (except single 0)
FAIL Indicators:
- Missing components (1.0)
- Too many components (1.0.0.0)
- Non-numeric components (1.x.0)
- Leading 'v' prefix
- Invalid separators
- Leading zeros (01.02.03)
Request: $ARGUMENTS
Operation: Check LICENSE File
Validate LICENSE file presence, format, and consistency with plugin metadata.
Parameters from $ARGUMENTS
- path: Target plugin/marketplace path (required)
- expected: Expected license type (optional, reads from plugin.json if not provided)
- strict: Enable strict validation mode (optional, default: false)
- check-consistency: Verify consistency with plugin.json (optional, default: true)
LICENSE Requirements
File Presence:
- LICENSE or LICENSE.txt in plugin root
- Also accept: LICENSE.md, COPYING, COPYING.txt
OSI-Approved Licenses (recommended):
- MIT License
- Apache License 2.0
- GNU General Public License (GPL) v2/v3
- BSD 2-Clause or 3-Clause License
- Mozilla Public License 2.0
- ISC License
- Creative Commons (for documentation)
Validation Checks:
- File exists: LICENSE file present in root
- Valid content: Contains recognized license text
- Complete: Full license text, not just license name
- Consistency: Matches license field in plugin.json
- OSI-approved: Recognized open-source license
Workflow
-
Locate LICENSE File
Check for files in plugin root (case-insensitive): - LICENSE - LICENSE.txt - LICENSE.md - COPYING - COPYING.txt - LICENCE (UK spelling) If multiple found, prefer LICENSE over others -
Read Plugin Metadata
Read plugin.json Extract license field value Store expected license type for comparison -
Execute License Detector
Execute .scripts/license-detector.py with parameters: - License file path - Expected license type (from plugin.json) - Strict mode flag Script returns: - detected_license: Identified license type - confidence: 0-100 (match confidence) - is_osi_approved: Boolean - is_complete: Boolean (full text vs just name) - matches_manifest: Boolean - issues: Array of problems -
Validate License Content
Check for license text patterns: - MIT: "Permission is hereby granted, free of charge..." - Apache 2.0: "Licensed under the Apache License, Version 2.0" - GPL-3.0: "GNU GENERAL PUBLIC LICENSE Version 3" - BSD-2-Clause: "Redistribution and use in source and binary forms" Detect incomplete licenses: - Just "MIT" or "MIT License" (missing full text) - Just "Apache 2.0" (missing full text) - Links to license without including text -
Check Consistency
Compare detected license with plugin.json: - Exact match: ✅ PASS - Close match (e.g., "MIT" vs "MIT License"): ⚠️ WARNING - Mismatch: ❌ ERROR - Not specified in plugin.json: ⚠️ WARNING Normalize license names for comparison: - "MIT License" == "MIT" - "Apache-2.0" == "Apache License 2.0" - "GPL-3.0" == "GNU GPL v3" -
Verify OSI Approval
Check against OSI-approved license list: - MIT: ✅ Approved - Apache-2.0: ✅ Approved - GPL-2.0, GPL-3.0: ✅ Approved - BSD-2-Clause, BSD-3-Clause: ✅ Approved - Proprietary: ❌ Not approved - Custom/Unknown: ⚠️ Review required -
Format Output
Display: - ✅/❌ File presence - Detected license type - OSI approval status - Consistency with plugin.json - Completeness (full text vs name only) - Issues and recommendations
Examples
# Check LICENSE with defaults (reads expected from plugin.json)
/documentation-validation license path:.
# Check with explicit expected license
/documentation-validation license path:. expected:MIT
# Strict validation (requires full license text)
/documentation-validation license path:. strict:true
# Skip consistency check (only validate file)
/documentation-validation license path:. check-consistency:false
# Check specific plugin
/documentation-validation license path:/path/to/plugin expected:Apache-2.0
Error Handling
Error: LICENSE file not found
❌ CRITICAL: LICENSE file not found in <path>
Remediation:
1. Create LICENSE file in plugin root directory
2. Include full license text (not just the name)
3. Use an OSI-approved open-source license (MIT recommended)
4. Ensure license field in plugin.json matches LICENSE file
Recommended licenses for plugins:
- MIT: Simple, permissive (most common)
- Apache 2.0: Permissive with patent grant
- GPL-3.0: Copyleft (requires derivatives to use same license)
- BSD-3-Clause: Permissive, similar to MIT
Full license texts available at: https://choosealicense.com/
This is a BLOCKING issue - plugin cannot be submitted without a LICENSE.
Error: Incomplete license text
⚠️ WARNING: LICENSE file contains only license name, not full text
Current content: "MIT License"
Required: Full MIT License text
The LICENSE file should contain the complete license text, not just the name.
For MIT License, include:
MIT License
Copyright (c) [year] [fullname]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
[full license text]
Get full text: https://opensource.org/licenses/MIT
Error: License mismatch with plugin.json
❌ ERROR: LICENSE file does not match plugin.json declaration
plugin.json declares: "Apache-2.0"
LICENSE file contains: "MIT License"
Remediation:
1. Update plugin.json to declare "MIT" license, OR
2. Replace LICENSE file with Apache 2.0 license text
Consistency is required - both files must specify the same license.
Error: Non-OSI-approved license
❌ ERROR: License is not OSI-approved
Detected license: "Proprietary" or "Custom License"
OpenPlugins marketplace requires OSI-approved open-source licenses.
Recommended licenses:
- MIT License (most permissive)
- Apache License 2.0
- GNU GPL v3
- BSD 3-Clause
Choose a license: https://choosealicense.com/
OSI-approved list: https://opensource.org/licenses
This is a BLOCKING issue - plugin cannot be submitted with proprietary license.
Error: Unrecognized license
⚠️ WARNING: Unable to identify license type
The LICENSE file content does not match known license patterns.
Possible issues:
- Custom or modified license (not allowed)
- Corrupted or incomplete license text
- Non-standard format
Remediation:
1. Use standard, unmodified license text from official source
2. Choose from OSI-approved licenses
3. Do not modify standard license text (except copyright holder)
4. Get standard text from https://choosealicense.com/
If using a valid OSI license, ensure text matches standard format exactly.
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LICENSE VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File: ✅ LICENSE found
License Type: <detected-license>
Confidence: <0-100>% ✅
OSI Approved: ✅ Yes
Complete Text: ✅ Yes (full license included)
Consistency Check:
plugin.json declares: "<license>"
LICENSE file contains: "<detected-license>"
Match: ✅ Consistent
Validation: ✅ PASS
Recommendations:
- License is valid and properly formatted
- Meets OpenPlugins requirements
- Ready for submission
Overall: <PASS|WARNINGS|FAIL>
Integration
This operation is invoked by:
/documentation-validation license path:.(direct)/documentation-validation full-docs path:.(as part of complete validation)/validation-orchestrator comprehensive path:.(via orchestrator)
Results contribute to documentation quality score:
- Present, valid, consistent: +5 points
- Present but issues: 0 points (with warnings)
- Missing: BLOCKING issue (-20 points)
Common License Patterns
MIT License Detection:
Pattern: "Permission is hereby granted, free of charge"
Confidence: 95%+
Apache 2.0 Detection:
Pattern: "Licensed under the Apache License, Version 2.0"
Confidence: 95%+
GPL-3.0 Detection:
Pattern: "GNU GENERAL PUBLIC LICENSE" + "Version 3"
Confidence: 95%+
BSD Detection:
Pattern: "Redistribution and use in source and binary forms"
Confidence: 90%+
Request: $ARGUMENTS
Operation: Check README Completeness
Validate README.md completeness, structure, and quality against OpenPlugins standards.
Parameters from $ARGUMENTS
- path: Target plugin/marketplace path (required)
- sections: Comma-separated required sections (optional, defaults to standard set)
- min-length: Minimum character count (optional, default: 500)
- strict: Enable strict validation mode (optional, default: false)
README Requirements
Required Sections (case-insensitive matching):
- Overview/Description: Plugin purpose and functionality
- Installation: How to install and configure
- Usage: How to use the plugin with examples
- Examples: At least 2-3 concrete usage examples
- License: License information or reference
Quality Criteria:
- Minimum 500 characters (configurable)
- No excessive placeholder text
- Proper markdown formatting
- Working links (if present)
- Code blocks properly formatted
Workflow
-
Locate README File
Check for README.md in plugin root If not found, check for README.txt or readme.md If still not found, report critical error -
Execute README Checker Script
Execute .scripts/readme-checker.py with parameters: - File path to README.md - Required sections list - Minimum length threshold - Strict mode flag Script returns JSON with: - sections_found: Array of detected sections - sections_missing: Array of missing sections - length: Character count - quality_score: 0-100 - issues: Array of specific problems -
Analyze Results
CRITICAL (blocking): - README.md file missing - Length < 200 characters - Missing 3+ required sections WARNING (should fix): - Length < 500 characters - Missing 1-2 required sections - Missing examples section RECOMMENDATION (nice to have): - Add troubleshooting section - Expand examples - Add badges or visual elements -
Calculate Section Score
score = 100 score -= (missing_required_sections × 15) score -= (length < 500) ? 10 : 0 score -= (no_examples) ? 15 : 0 score = max(0, score) -
Format Output
Display: - ✅/❌ File presence - ✅/⚠️/❌ Each required section - Length statistics - Quality score - Specific improvement recommendations
Examples
# Check README with defaults
/documentation-validation readme path:.
# Check with custom sections
/documentation-validation readme path:./my-plugin sections:"overview,installation,usage,examples,contributing,license"
# Strict validation with higher standards
/documentation-validation readme path:. min-length:1000 strict:true
# Check specific plugin
/documentation-validation readme path:/path/to/plugin sections:"overview,usage,license"
Error Handling
Error: README.md not found
❌ CRITICAL: README.md file not found in <path>
Remediation:
1. Create README.md in plugin root directory
2. Include required sections: Overview, Installation, Usage, Examples, License
3. Ensure minimum 500 characters of meaningful content
4. See https://github.com/dhofheinz/open-plugins/blob/main/README.md for example
This is a BLOCKING issue - plugin cannot be submitted without README.
Error: README too short
⚠️ WARNING: README.md is only <X> characters (minimum: 500)
Current length: <X> characters
Required: 500 characters minimum
Gap: <500-X> characters
Remediation:
- Expand installation instructions with examples
- Add 2-3 usage examples with code blocks
- Include configuration options
- Add troubleshooting section
Error: Missing required sections
❌ ERROR: Missing <N> required sections
Missing sections:
- Installation: How to install the plugin
- Examples: At least 2 concrete usage examples
- License: License information or reference to LICENSE file
Remediation:
Add each missing section with meaningful content.
See CONTRIBUTING.md for section requirements.
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
README VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File: ✅ README.md found
Required Sections:
✅ Overview/Description
✅ Installation
✅ Usage
⚠️ Examples (found 1, recommended: 3+)
✅ License
Length: <X> characters (minimum: 500) ✅
Quality Score: <0-100>/100
Issues Found: <N>
Critical (blocking): <count>
Warnings (should fix): <count>
Recommendations: <count>
Top Recommendations:
1. Add 2 more usage examples with code blocks [+15 pts]
2. Expand installation section with configuration options [+5 pts]
3. Include troubleshooting section [+5 pts]
Overall: <PASS|WARNINGS|FAIL>
Integration
This operation is invoked by:
/documentation-validation readme path:.(direct)/documentation-validation full-docs path:.(as part of complete validation)/validation-orchestrator comprehensive path:.(via orchestrator)
Results feed into quality-analysis scoring system.
Request: $ARGUMENTS
Operation: Full Documentation Validation
Execute comprehensive documentation validation workflow covering all documentation aspects.
Parameters from $ARGUMENTS
- path: Target plugin/marketplace path (required)
- detailed: Include detailed sub-reports (optional, default: true)
- fix-suggestions: Generate actionable improvement suggestions (optional, default: true)
- format: Output format (text|json|markdown) (optional, default: text)
Full Documentation Workflow
This operation orchestrates all documentation validation sub-operations to provide a complete documentation quality assessment.
Workflow
-
Initialize Validation Context
Create validation context: - Target path - Timestamp - Validation mode: comprehensive - Results storage structure Prepare for aggregating results from: - README validation - CHANGELOG validation - LICENSE validation - Examples validation -
Execute README Validation
Invoke: check-readme.md operation Parameters: - path: <target-path> - sections: default required sections - min-length: 500 Capture results: - README present: Boolean - Sections found: Array - Sections missing: Array - Length: Integer - Score: 0-100 - Issues: Array -
Execute CHANGELOG Validation
Invoke: validate-changelog.md operation Parameters: - file: CHANGELOG.md - format: keepachangelog - require-unreleased: true Capture results: - CHANGELOG present: Boolean - Format compliance: 0-100% - Version entries: Array - Issues: Array - Score: 0-100 -
Execute LICENSE Validation
Invoke: check-license.md operation Parameters: - path: <target-path> - check-consistency: true Capture results: - LICENSE present: Boolean - License type: String - OSI approved: Boolean - Consistent with manifest: Boolean - Issues: Array - Score: 0-100 -
Execute Examples Validation
Invoke: validate-examples.md operation Parameters: - path: <target-path> - no-placeholders: true - recursive: true Capture results: - Files checked: Integer - Examples found: Integer - Placeholders detected: Integer - Quality score: 0-100 - Issues: Array -
Aggregate Results
Calculate overall documentation score: weights = { readme: 40%, # Most important examples: 30%, # Critical for usability license: 20%, # Required for submission changelog: 10% # Recommended but not critical } overall_score = ( readme_score × 0.40 + examples_score × 0.30 + license_score × 0.20 + changelog_score × 0.10 ) Round to integer: 0-100 -
Categorize Issues by Priority
CRITICAL (P0 - Blocking): - README.md missing - LICENSE file missing - README < 200 characters - Non-OSI-approved license - License mismatch with manifest IMPORTANT (P1 - Should Fix): - README missing 2+ required sections - README < 500 characters - No examples in README - 5+ placeholder patterns - CHANGELOG has format errors RECOMMENDED (P2 - Nice to Have): - CHANGELOG missing - README missing optional sections - < 3 examples - Minor placeholder patterns -
Generate Improvement Roadmap
Create prioritized action plan: For each issue: - Identify impact on overall score - Estimate effort (Low/Medium/High) - Calculate score improvement - Generate specific remediation steps Sort by: Priority → Score Impact → Effort Example: 1. [P0] Add LICENSE file → +20 pts → 15 min 2. [P1] Expand README to 500+ chars → +10 pts → 30 min 3. [P1] Add 2 usage examples → +15 pts → 20 min 4. [P2] Create CHANGELOG.md → +10 pts → 15 min -
Determine Publication Readiness
Publication readiness determination: READY (90-100): - All critical requirements met - High-quality documentation - No blocking issues - Immediate submission recommended READY WITH MINOR IMPROVEMENTS (75-89): - Critical requirements met - Some recommended improvements - Can submit, but improvements increase quality - Suggested: Address P1 issues before submission NEEDS WORK (60-74): - Critical requirements met - Several important issues - Should address P1 issues before submission - Documentation needs expansion NOT READY (<60): - Critical issues present - Insufficient documentation quality - Must address P0 and P1 issues - Submission will be rejected -
Format Output
Based on format parameter: - text: Human-readable report - json: Structured JSON for automation - markdown: Formatted markdown report
Examples
# Full documentation validation with defaults
/documentation-validation full-docs path:.
# With detailed sub-reports
/documentation-validation full-docs path:. detailed:true
# JSON output for automation
/documentation-validation full-docs path:. format:json
# Without fix suggestions (faster)
/documentation-validation full-docs path:. fix-suggestions:false
# Validate specific plugin
/documentation-validation full-docs path:/path/to/plugin
Error Handling
Error: Multiple critical issues
❌ CRITICAL: Multiple blocking documentation issues
Documentation Score: <score>/100 ⚠️
BLOCKING ISSUES (<count>):
1. README.md not found
→ Create README.md with required sections
→ Minimum 500 characters
→ Include Overview, Installation, Usage, Examples, License
2. LICENSE file not found
→ Create LICENSE file with OSI-approved license
→ MIT License recommended
→ Must match plugin.json license field
3. License mismatch
→ plugin.json declares "Apache-2.0"
→ LICENSE file contains "MIT"
→ Update one to match the other
IMPORTANT ISSUES (<count>):
- README missing Examples section
- No code examples found
- CHANGELOG.md recommended
YOUR NEXT STEPS:
1. Add LICENSE file (CRITICAL - 15 minutes)
2. Create comprehensive README.md (CRITICAL - 30 minutes)
3. Add 3 usage examples (IMPORTANT - 20 minutes)
After addressing critical issues, revalidate with:
/documentation-validation full-docs path:.
Error: Documentation too sparse
⚠️ WARNING: Documentation exists but is too sparse
Documentation Score: 65/100 ⚠️
Your documentation meets minimum requirements but needs expansion
for professional quality.
AREAS NEEDING IMPROVEMENT:
1. README is only 342 characters (minimum: 500)
→ Expand installation instructions
→ Add more detailed usage examples
→ Include troubleshooting section
2. Only 1 example found (recommended: 3+)
→ Add basic usage example
→ Add advanced example
→ Add configuration example
3. CHANGELOG missing
→ Create CHANGELOG.md
→ Use Keep a Changelog format
→ Document version 1.0.0 features
IMPACT:
Current: 65/100 (Fair)
After improvements: ~85/100 (Good)
Time investment: ~45 minutes
Quality improvement: +20 points
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPREHENSIVE DOCUMENTATION VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: <path>
Type: <marketplace|plugin>
Timestamp: <YYYY-MM-DD HH:MM:SS>
OVERALL DOCUMENTATION SCORE: <0-100>/100 <⭐⭐⭐⭐⭐>
Rating: <Excellent|Good|Fair|Needs Improvement|Poor>
Publication Ready: <Yes|Yes with improvements|Needs work|No>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPONENT SCORES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
README (Weight: 40%)
Score: <0-100>/100 ✅
Status: ✅ Complete and comprehensive
Sections: <N>/5 required sections found
Length: <N> characters (minimum: 500) ✅
Issues: None
EXAMPLES (Weight: 30%)
Score: <0-100>/100 ⚠️
Status: ⚠️ Could be improved
Examples found: <N> (recommended: 3+)
Placeholders: <N> detected
Issues: <N> placeholder patterns found
LICENSE (Weight: 20%)
Score: <0-100>/100 ✅
Status: ✅ Valid and consistent
Type: MIT License
OSI Approved: ✅ Yes
Consistency: ✅ Matches plugin.json
Issues: None
CHANGELOG (Weight: 10%)
Score: <0-100>/100 ⚠️
Status: ⚠️ Missing (recommended but not required)
Format: N/A
Versions: 0
Issues: CHANGELOG.md not found
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ISSUES SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Critical (P0 - Blocking): <count>
Important (P1 - Should Fix): <count>
Recommended (P2 - Nice to Have): <count>
CRITICAL ISSUES:
[None - Ready for submission] ✅
IMPORTANT ISSUES:
⚠️ 1. Add 2 more usage examples to README
Impact: +15 points
Effort: Low (20 minutes)
⚠️ 2. Replace 3 placeholder patterns in examples
Impact: +10 points
Effort: Low (10 minutes)
RECOMMENDATIONS:
💡 1. Create CHANGELOG.md for version tracking
Impact: +10 points
Effort: Low (15 minutes)
💡 2. Add troubleshooting section to README
Impact: +5 points
Effort: Low (15 minutes)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
IMPROVEMENT ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Current Score: <score>/100
Target Score: 90/100 (Excellent - Publication Ready)
Gap: <gap> points
RECOMMENDED ACTIONS (to reach 90+):
1. [+15 pts] Add usage examples
Priority: High
Effort: 20 minutes
Description:
- Add 2 more concrete usage examples to README
- Include basic, intermediate, and advanced scenarios
- Use real plugin commands and parameters
2. [+10 pts] Clean up placeholder patterns
Priority: Medium
Effort: 10 minutes
Description:
- Replace "YOUR_VALUE" patterns with concrete examples
- Complete or remove TODO markers
- Use template syntax (${VAR}) for user-provided values
3. [+10 pts] Create CHANGELOG.md
Priority: Medium
Effort: 15 minutes
Description:
- Use Keep a Changelog format
- Document version 1.0.0 initial release
- Add [Unreleased] section for future changes
AFTER IMPROVEMENTS:
Projected Score: ~90/100 ⭐⭐⭐⭐⭐
Time Investment: ~45 minutes
Status: Excellent - Ready for submission
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PUBLICATION READINESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: ✅ READY WITH MINOR IMPROVEMENTS
Your plugin documentation meets all critical requirements and is ready
for submission to OpenPlugins marketplace. The recommended improvements
above will increase quality score and provide better user experience.
✅ Strengths:
- Comprehensive README with all required sections
- Valid OSI-approved license (MIT)
- License consistent with plugin.json
- Good documentation structure
⚠️ Improvement Opportunities:
- Add more usage examples for better user onboarding
- Create CHANGELOG for version tracking
- Clean up minor placeholder patterns
NEXT STEPS:
1. (Optional) Address recommended improvements (~45 min)
2. Run validation again to verify improvements
3. Submit to OpenPlugins marketplace
Command to revalidate:
/documentation-validation full-docs path:.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Integration
This operation is the primary entry point for complete documentation validation:
Invoked by:
/documentation-validation full-docs path:.(direct invocation)/validation-orchestrator comprehensive path:.(as part of full plugin validation)- marketplace-validator agent (automatic documentation assessment)
Invokes sub-operations:
/documentation-validation readme path:./documentation-validation changelog file:CHANGELOG.md/documentation-validation license path:./documentation-validation examples path:.
Feeds results to:
/quality-analysis full-analysis(for overall quality scoring)/quality-analysis generate-report(for report generation)
JSON Output Format
When format:json is specified:
{
"validation_type": "full-documentation",
"target_path": "/path/to/plugin",
"timestamp": "2025-01-15T10:30:00Z",
"overall_score": 85,
"rating": "Good",
"publication_ready": "yes_with_improvements",
"components": {
"readme": {
"score": 90,
"status": "pass",
"present": true,
"sections_found": 5,
"sections_missing": 0,
"length": 1234,
"issues": []
},
"changelog": {
"score": 70,
"status": "warning",
"present": true,
"compliance": 70,
"issues": ["Invalid version header format"]
},
"license": {
"score": 100,
"status": "pass",
"present": true,
"type": "MIT",
"osi_approved": true,
"consistent": true,
"issues": []
},
"examples": {
"score": 75,
"status": "warning",
"examples_found": 2,
"placeholders_detected": 3,
"issues": ["Placeholder patterns detected"]
}
},
"issues": {
"critical": [],
"important": [
{
"component": "examples",
"message": "Add 2 more usage examples",
"impact": 15,
"effort": "low"
}
],
"recommended": [
{
"component": "readme",
"message": "Add troubleshooting section",
"impact": 5,
"effort": "low"
}
]
},
"improvement_roadmap": [
{
"action": "Add usage examples",
"points": 15,
"priority": "high",
"effort": "20 minutes"
}
],
"projected_score_after_improvements": 95
}
Request: $ARGUMENTS
You are the Documentation Validation coordinator, ensuring comprehensive and high-quality documentation.
Your Mission
Parse $ARGUMENTS to determine the requested documentation validation operation and route to the appropriate sub-command.
Available Operations
Parse the first word of $ARGUMENTS to determine which operation to execute:
- readme → Read
.claude/commands/documentation-validation/check-readme.md - changelog → Read
.claude/commands/documentation-validation/validate-changelog.md - license → Read
.claude/commands/documentation-validation/check-license.md - examples → Read
.claude/commands/documentation-validation/validate-examples.md - full-docs → Read
.claude/commands/documentation-validation/full-documentation.md
Argument Format
/documentation-validation <operation> [parameters]
Examples
# Check README completeness
/documentation-validation readme path:. sections:"overview,installation,usage,examples"
# Validate CHANGELOG format
/documentation-validation changelog file:CHANGELOG.md format:keepachangelog
# Check LICENSE file
/documentation-validation license path:. expected:MIT
# Validate example quality
/documentation-validation examples path:. no-placeholders:true
# Run complete documentation validation
/documentation-validation full-docs path:.
Documentation Standards
README.md Requirements:
- Overview/Description section
- Installation instructions
- Usage examples (minimum 2)
- Configuration options (if applicable)
- License information
- Length: Minimum 500 characters
CHANGELOG.md Requirements:
- Keep a Changelog format
- Version headers ([X.Y.Z] - YYYY-MM-DD)
- Change categories: Added, Changed, Deprecated, Removed, Fixed, Security
- Unreleased section for upcoming changes
LICENSE Requirements:
- LICENSE or LICENSE.txt file present
- Valid OSI-approved license
- License matches plugin.json declaration
Examples Requirements:
- No placeholder text (TODO, FIXME, XXX, placeholder)
- Complete, runnable examples
- Real values, not dummy data
- Proper formatting and syntax
Quality Scoring
Documentation contributes to overall quality score:
- Complete README: +15 points
- CHANGELOG present: +10 points
- LICENSE valid: +5 points
- Quality examples: +10 points
Error Handling
If the operation is not recognized:
- List all available documentation operations
- Show documentation standards
- Provide improvement suggestions
Base Directory
Base directory for this skill: .claude/commands/documentation-validation/
Your Task
- Parse
$ARGUMENTSto extract operation and parameters - Read the corresponding operation file
- Execute documentation validation checks
- Return detailed findings with specific improvement guidance
Current Request: $ARGUMENTS
Operation: Validate CHANGELOG Format
Validate CHANGELOG.md format compliance with "Keep a Changelog" standard.
Parameters from $ARGUMENTS
- file: Path to CHANGELOG file (optional, default: CHANGELOG.md)
- format: Expected format (optional, default: keepachangelog)
- strict: Enable strict validation (optional, default: false)
- require-unreleased: Require [Unreleased] section (optional, default: true)
CHANGELOG Requirements
Keep a Changelog Format (https://keepachangelog.com/):
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- New features not yet released
## [1.0.0] - 2025-01-15
### Added
- Initial release feature
### Changed
- Modified behavior
### Fixed
- Bug fixes
Required Elements:
- Title: "Changelog" or "Change Log"
- Version Headers:
## [X.Y.Z] - YYYY-MM-DDformat - Change Categories: Added, Changed, Deprecated, Removed, Fixed, Security
- Unreleased Section:
## [Unreleased]for upcoming changes - Chronological Order: Newest versions first
Valid Change Categories:
- Added: New features
- Changed: Changes in existing functionality
- Deprecated: Soon-to-be removed features
- Removed: Removed features
- Fixed: Bug fixes
- Security: Security vulnerability fixes
Workflow
-
Locate CHANGELOG File
Check for CHANGELOG.md in plugin root Also check: CHANGELOG, CHANGELOG.txt, changelog.md, HISTORY.md If not found, report as missing (WARNING, not CRITICAL) -
Execute CHANGELOG Validator
Execute .scripts/changelog-validator.sh with parameters: - File path to CHANGELOG - Expected format (keepachangelog) - Strict mode flag - Require unreleased flag Script returns: - has_title: Boolean - has_unreleased: Boolean - version_headers: Array of version entries - categories_used: Array of change categories - issues: Array of format violations - compliance_score: 0-100 -
Validate Version Headers
For each version header: - Check format: ## [X.Y.Z] - YYYY-MM-DD - Validate semantic version (X.Y.Z) - Validate date format (YYYY-MM-DD) - Check chronological order (newest first) Common violations: - Missing brackets: ## 1.0.0 - 2025-01-15 (should be [1.0.0]) - Wrong date format: ## [1.0.0] - 01/15/2025 - Invalid semver: ## [1.0] - 2025-01-15 -
Validate Change Categories
For each version section: - Check for valid category headers (### Added, ### Fixed, etc.) - Warn if no categories used - Recommend appropriate categories Invalid category examples: - "### New Features" (should be "### Added") - "### Bugs" (should be "### Fixed") - "### Updates" (should be "### Changed") -
Calculate Compliance Score
score = 100 score -= (!has_title) ? 10 : 0 score -= (!has_unreleased) ? 15 : 0 score -= (invalid_version_headers × 10) score -= (invalid_categories × 5) score -= (wrong_date_format × 5) score = max(0, score) -
Format Output
Display: - ✅/⚠️/❌ File presence - ✅/❌ Format compliance - ✅/⚠️ Version headers - ✅/⚠️ Change categories - Compliance score - Specific violations - Improvement recommendations
Examples
# Validate default CHANGELOG.md
/documentation-validation changelog file:CHANGELOG.md
# Validate with custom path
/documentation-validation changelog file:./HISTORY.md
# Strict validation (all elements required)
/documentation-validation changelog file:CHANGELOG.md strict:true
# Don't require Unreleased section
/documentation-validation changelog file:CHANGELOG.md require-unreleased:false
# Part of full documentation check
/documentation-validation full-docs path:.
Error Handling
Error: CHANGELOG not found
⚠️ WARNING: CHANGELOG.md not found in <path>
Remediation:
1. Create CHANGELOG.md in plugin root directory
2. Use "Keep a Changelog" format (https://keepachangelog.com/)
3. Include [Unreleased] section for upcoming changes
4. Document version history with proper headers
Example:
# Changelog
## [Unreleased]
### Added
- Features in development
## [1.0.0] - 2025-01-15
### Added
- Initial release
Note: CHANGELOG is recommended but not required for initial submission.
It becomes important for version updates.
Error: Invalid version header format
❌ ERROR: Invalid version header format detected
Invalid headers found:
- Line 10: "## 1.0.0 - 2025-01-15" (missing brackets)
- Line 25: "## [1.0] - 01/15/2025" (invalid semver and date format)
Correct format:
## [X.Y.Z] - YYYY-MM-DD
Examples:
- ## [1.0.0] - 2025-01-15
- ## [2.1.3] - 2024-12-20
- ## [0.1.0] - 2024-11-05
Remediation:
1. Add brackets around version numbers: [1.0.0]
2. Use semantic versioning: MAJOR.MINOR.PATCH
3. Use ISO date format: YYYY-MM-DD
Error: Missing Unreleased section
⚠️ WARNING: Missing [Unreleased] section
The Keep a Changelog format recommends an [Unreleased] section for tracking
upcoming changes before they're officially released.
Add to top of CHANGELOG (after title):
## [Unreleased]
### Added
- Features in development
### Changed
- Planned changes
Error: Invalid change categories
⚠️ WARNING: Non-standard change categories detected
Invalid categories found:
- "### New Features" (should be "### Added")
- "### Bug Fixes" (should be "### Fixed")
- "### Updates" (should be "### Changed")
Valid categories:
- Added: New features
- Changed: Changes in existing functionality
- Deprecated: Soon-to-be removed features
- Removed: Removed features
- Fixed: Bug fixes
- Security: Security vulnerability fixes
Remediation:
Replace non-standard categories with Keep a Changelog categories.
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CHANGELOG VALIDATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File: ✅ CHANGELOG.md found
Format: Keep a Changelog
Compliance: <0-100>% ✅/⚠️/❌
Structure:
✅ Title present
✅ [Unreleased] section present
✅ Version headers formatted correctly
✅ Change categories valid
Version Entries: <count>
- [1.0.0] - 2025-01-15 ✅
- [0.2.0] - 2024-12-20 ✅
- [0.1.0] - 2024-11-05 ✅
Change Categories Used:
✅ Added (3 versions)
✅ Changed (2 versions)
✅ Fixed (3 versions)
Issues Found: <N>
Violations:
<List specific issues if any>
Recommendations:
1. Add Security category for vulnerability fixes
2. Expand [Unreleased] section with upcoming features
3. Add links to version comparison (optional)
Overall: <PASS|WARNINGS|FAIL>
Integration
This operation is invoked by:
/documentation-validation changelog file:CHANGELOG.md(direct)/documentation-validation full-docs path:.(as part of complete validation)/validation-orchestrator comprehensive path:.(via orchestrator)
Results contribute to documentation quality score:
- Present and compliant: +10 points
- Present but non-compliant: +5 points
- Missing: 0 points (warning but not blocking)
Request: $ARGUMENTS
Operation: Validate Example Quality
Validate example code quality, detecting placeholders and ensuring examples are complete and runnable.
Parameters from $ARGUMENTS
- path: Target plugin/marketplace path (required)
- no-placeholders: Strict placeholder enforcement (optional, default: true)
- recursive: Check all markdown and code files recursively (optional, default: true)
- extensions: File extensions to check (optional, default: "md,txt,json,sh,py,js")
Example Quality Requirements
Complete Examples:
- Concrete, runnable code or commands
- Real values, not placeholder text
- Proper syntax and formatting
- Context and explanations
- Expected output or results
No Placeholder Patterns:
- TODO:
TODO,@TODO,// TODO: - FIXME:
FIXME,@FIXME,// FIXME: - XXX:
XXX,@XXX,// XXX: - Placeholders:
placeholder,PLACEHOLDER,your-value-here,<your-value>,[YOUR-VALUE] - Generic:
example,sample,test,dummy,foo,bar,baz - User substitution:
<username>,<your-email>,your-api-key,INSERT-HERE
Acceptable Patterns (not placeholders):
- Template variables:
{{variable}},${variable},$VARIABLE - Documentation examples:
<name>,[optional]in usage syntax - Actual values: Real plugin names, real commands, concrete examples
Workflow
-
Identify Files to Validate
Scan plugin directory for documentation files: - README.md (primary source) - CONTRIBUTING.md - docs/**/*.md - examples/**/* - *.sh, *.py, *.js (example scripts) If recursive:false, only check README.md -
Execute Example Validator
Execute .scripts/example-validator.sh with parameters: - Path to plugin directory - No-placeholders flag - Recursive flag - File extensions to check Script returns: - files_checked: Count of files analyzed - placeholders_found: Array of placeholder instances - files_with_issues: Array of files containing placeholders - example_count: Number of code examples found - quality_score: 0-100 -
Detect Placeholder Patterns
Search for patterns (case-insensitive): # TODO/FIXME/XXX markers grep -iE '(TODO|FIXME|XXX|HACK)[:)]' <files> # Placeholder text grep -iE '(placeholder|your-.*-here|<your-|INSERT.?HERE)' <files> # Generic dummy values grep -iE '\b(foo|bar|baz|dummy|sample|test)\b' <files> # User substitution patterns grep -iE '(<username>|<email>|<api-key>|YOUR_[A-Z_]+)' <files> # Exclude: - Comments explaining placeholders - Documentation of template syntax - Proper template variables ({{x}}, ${x}) -
Analyze Code Blocks
For each code block in markdown: - Extract language and content - Check for placeholder patterns - Verify syntax highlighting specified - Ensure examples are complete Example extraction: ```bash /plugin install my-plugin@marketplace ✅ Concrete /plugin install <plugin-name> ⚠️ Documentation (acceptable) /plugin install YOUR_PLUGIN ❌ Placeholder -
Count and Categorize Examples
Count examples by type: - Command examples: /plugin install ... - Configuration examples: JSON snippets - Code examples: Script samples - Usage examples: Real-world scenarios Quality criteria: - At least 2-3 concrete examples - Examples cover primary use cases - Examples are copy-pasteable -
Calculate Quality Score
score = 100 score -= (placeholder_instances × 10) # -10 per placeholder score -= (todo_markers × 5) # -5 per TODO/FIXME score -= (example_count < 2) ? 20 : 0 # -20 if < 2 examples score -= (incomplete_examples × 15) # -15 per incomplete example score = max(0, score) -
Format Output
Display: - Files checked count - Examples found count - Placeholders detected - Quality score - Specific issues with file/line references - Improvement recommendations
Examples
# Validate examples with strict placeholder checking (default)
/documentation-validation examples path:.
# Check only README.md (non-recursive)
/documentation-validation examples path:. recursive:false
# Allow placeholders (lenient mode)
/documentation-validation examples path:. no-placeholders:false
# Check specific file extensions
/documentation-validation examples path:. extensions:"md,sh,py"
# Strict validation of examples directory
/documentation-validation examples path:./examples no-placeholders:true recursive:true
Error Handling
Error: Placeholders detected
⚠️ WARNING: Placeholder patterns detected in examples
Placeholders found: <N> instances across <M> files
README.md:
- Line 45: /plugin install YOUR_PLUGIN_NAME
^ Should be concrete plugin name
- Line 67: API_KEY=your-api-key-here
^ Should be removed or use template syntax
examples/usage.sh:
- Line 12: # TODO: Add authentication example
^ Complete example or remove TODO
Remediation:
1. Replace "YOUR_PLUGIN_NAME" with actual plugin name
2. Use template syntax for user-provided values: ${API_KEY}
3. Remove TODO markers - complete examples or remove them
4. Provide concrete, copy-pasteable examples
Acceptable patterns:
- Template variables: ${VARIABLE}, {{variable}}
- Documentation syntax: <name> in usage descriptions
- Generic placeholders in template explanations
Error: Too few examples
⚠️ WARNING: Insufficient examples in documentation
Examples found: <N> (minimum recommended: 3)
README.md contains <N> code examples:
- Installation example ✅
- Basic usage ❌ Missing
- Advanced usage ❌ Missing
Remediation:
Add at least 2-3 concrete usage examples showing:
1. Basic usage (most common scenario)
2. Common configuration options
3. Advanced or specialized use case
Example structure:
```bash
# Basic usage
/my-plugin action param:value
# With options
/my-plugin action param:value option:true
# Advanced example
/my-plugin complex-action config:custom nested:value
Good examples are copy-pasteable and use real values.
**Error: Incomplete examples**
⚠️ WARNING: Incomplete or broken examples detected
Incomplete examples:
README.md:
- Line 34: Code block with syntax error
- Line 56: Example missing expected output
- Line 78: Example truncated with "..."
Remediation:
- Ensure all code examples are syntactically valid
- Show expected output or results after examples
- Complete truncated examples (no "..." placeholders)
- Test examples before including in documentation
Example format:
# Command with description
/plugin install example-plugin@marketplace
# Expected output:
# ✓ Installing example-plugin@marketplace
# ✓ Plugin installed successfully
**Error: Generic dummy values**
⚠️ WARNING: Generic placeholder values detected
Generic values found:
- README.md:45 - "foo", "bar" used as example values
- examples/config.json:12 - "sample" as placeholder
While "foo/bar" are common in documentation, concrete examples are more helpful for users.
Remediation: Replace generic values with realistic examples:
- Instead of "foo", use actual plugin name
- Instead of "bar", use real parameter value
- Instead of "sample", use concrete example
Good: /my-plugin process file:README.md Bad: /my-plugin process file:foo.txt
### Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ EXAMPLE QUALITY VALIDATION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files Checked: Code Examples Found:
Example Count by Type:
- Command examples: ✅
- Configuration examples: ✅
- Usage examples: ⚠️ (recommend 3+)
Placeholder Detection: TODO/FIXME markers: ❌ Placeholder patterns: ❌ Generic values (foo/bar): ⚠️
Quality Score: <0-100>/100
Issues by File: README.md: issues ├─ Line 45: YOUR_PLUGIN_NAME (placeholder) ├─ Line 67: TODO marker └─ Line 89: Generic "foo" value
examples/usage.sh: issues └─ Line 12: Incomplete example
Recommendations:
- Replace placeholder patterns with concrete values [+10 pts]
- Complete or remove TODO markers [+5 pts]
- Add more usage examples [+15 pts]
Overall: <PASS|WARNINGS|FAIL>
### Integration
This operation is invoked by:
- `/documentation-validation examples path:.` (direct)
- `/documentation-validation full-docs path:.` (as part of complete validation)
- `/validation-orchestrator comprehensive path:.` (via orchestrator)
Results contribute to documentation quality score:
- High-quality examples (90+): +10 points
- Some issues (60-89): +5 points
- Poor quality (<60): 0 points
- Missing examples: -10 points
### Special Cases
**Template Documentation**:
If the plugin provides templates or scaffolding, some placeholders
are acceptable when properly documented as template variables.
Example:
```markdown
The generated code includes template variables:
- {{PROJECT_NAME}} - Will be replaced with actual project name
- {{AUTHOR}} - Will be replaced with author information
This is acceptable because the placeholders are documented as intentional template syntax.
Request: $ARGUMENTS
Operation: Calculate Quality Score
Calculate comprehensive quality score (0-100) based on validation results with star rating.
Parameters from $ARGUMENTS
Extract these parameters from $ARGUMENTS:
- path: Target path to analyze (required)
- errors: Critical error count (default: 0)
- warnings: Warning count (default: 0)
- missing: Missing recommended fields count (default: 0)
Scoring Algorithm
Execute the quality scoring algorithm using .scripts/scoring-algorithm.py:
Algorithm:
score = 100
score -= (errors × 20) # Critical errors: -20 points each
score -= (warnings × 10) # Warnings: -10 points each
score -= (missing × 5) # Missing recommended: -5 points each
score = max(0, score) # Floor at 0
Rating Thresholds:
- 90-100: Excellent ⭐⭐⭐⭐⭐ (publication-ready)
- 75-89: Good ⭐⭐⭐⭐ (ready with minor improvements)
- 60-74: Fair ⭐⭐⭐ (needs work)
- 40-59: Needs Improvement ⭐⭐ (substantial work needed)
- 0-39: Poor ⭐ (major overhaul required)
Workflow
-
Parse Arguments
Extract path, errors, warnings, missing from $ARGUMENTS Validate that path exists Set defaults for missing parameters -
Calculate Score
Invoke Bash tool to execute: python3 .claude/commands/quality-analysis/.scripts/scoring-algorithm.py \ --errors $errors \ --warnings $warnings \ --missing $missing -
Format Output
Display results in user-friendly format with: - Numeric score (0-100) - Rating (Excellent/Good/Fair/Needs Improvement/Poor) - Star rating (⭐⭐⭐⭐⭐) - Publication readiness status
Examples
# Calculate score with validation results
/quality-analysis score path:. errors:2 warnings:5 missing:3
# Calculate perfect score
/quality-analysis score path:. errors:0 warnings:0 missing:0
# Calculate score with only errors
/quality-analysis score path:. errors:3
Error Handling
- Missing path: Request path parameter
- Invalid counts: Negative numbers default to 0
- Script not found: Provide clear error message with remediation
- Python not available: Fallback to bash calculation
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
QUALITY SCORE CALCULATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: <path>
Score: <0-100>/100
Rating: <Excellent|Good|Fair|Needs Improvement|Poor>
Stars: <⭐⭐⭐⭐⭐>
Breakdown:
Base Score: 100
Critical Errors: -<errors × 20>
Warnings: -<warnings × 10>
Missing Fields: -<missing × 5>
─────────────────────
Final Score: <score>/100
Publication Ready: <Yes|With Minor Changes|Needs Work|Not Ready>
Integration Notes
This operation is typically invoked by:
full-analysis.mdas first stepvalidation-orchestratorafter comprehensive validation- Direct user invocation for score-only calculation
Request: $ARGUMENTS
Operation: Full Quality Analysis
Execute comprehensive quality analysis orchestrating all sub-operations to generate complete assessment.
Parameters from $ARGUMENTS
Extract these parameters from $ARGUMENTS:
- path: Target path to analyze (required)
- context: Path to validation context JSON file with prior results (optional)
- format: Report output format - markdown|json|html (default: markdown)
- output: Output file path for report (optional)
Full Analysis Workflow
This operation orchestrates all quality-analysis sub-operations to provide a complete quality assessment.
1. Load Validation Context
IF context parameter provided:
Read validation results from JSON file
Extract:
- Errors count
- Warnings count
- Missing fields count
- Validation layer results
- Detailed issue list
ELSE:
Use default values:
- errors: 0
- warnings: 0
- missing: 0
2. Calculate Base Score
Read calculate-score.md operation instructions
Execute scoring with validation results:
python3 .scripts/scoring-algorithm.py \
--errors $errors \
--warnings $warnings \
--missing $missing \
--format json
Capture:
- Quality score (0-100)
- Rating (Excellent/Good/Fair/Needs Improvement/Poor)
- Star rating (⭐⭐⭐⭐⭐)
- Publication readiness status
3. Prioritize All Issues
Read prioritize-issues.md operation instructions
IF context has issues:
Write issues to temporary JSON file
Execute issue prioritization:
bash .scripts/issue-prioritizer.sh $temp_issues_file
Capture:
- P0 (Critical) issues with details
- P1 (Important) issues with details
- P2 (Recommended) issues with details
ELSE:
Skip (no issues to prioritize)
4. Generate Improvement Suggestions
Read suggest-improvements.md operation instructions
Generate actionable recommendations:
Target score: 90 (publication-ready)
Current score: $calculated_score
Generate suggestions for:
- Quick wins (< 30 min, high impact)
- This week improvements (< 2 hours)
- Long-term enhancements
Include:
- Score impact per suggestion
- Effort estimates
- Priority assignment
- Detailed fix instructions
5. Generate Comprehensive Report
Read generate-report.md operation instructions
Execute report generation:
python3 .scripts/report-generator.py \
--path $path \
--format $format \
--context $aggregated_context \
--output $output
Report includes:
- Executive summary
- Quality score and rating
- Validation layer breakdown
- Prioritized issues (P0/P1/P2)
- Improvement recommendations
- Detailed findings
6. Aggregate and Display Results
Combine all outputs into unified assessment:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPREHENSIVE QUALITY ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: <path>
Type: <marketplace|plugin>
Analyzed: <timestamp>
QUALITY SCORE: <0-100>/100 <⭐⭐⭐⭐⭐>
Rating: <rating>
Publication Ready: <Yes|No|With Changes>
CRITICAL ISSUES: <P0 count>
IMPORTANT ISSUES: <P1 count>
RECOMMENDATIONS: <P2 count>
[Executive Summary - 2-3 sentences on readiness]
[If not publication-ready, show top 3 quick wins]
[Report file location if output specified]
Workflow Steps
-
Initialize Analysis
Validate path exists Load validation context if provided Set up temporary files for intermediate results -
Execute Operations Sequentially
Step 1: Calculate Score └─→ Invoke scoring-algorithm.py └─→ Store result in context Step 2: Prioritize Issues (if issues exist) └─→ Invoke issue-prioritizer.sh └─→ Store categorized issues in context Step 3: Generate Suggestions └─→ Analyze score gap └─→ Create actionable recommendations └─→ Store in context Step 4: Generate Report └─→ Invoke report-generator.py └─→ Aggregate all context data └─→ Format in requested format └─→ Output to file or stdout -
Present Summary
Display high-level results Show publication readiness Highlight critical blockers (if any) Show top quick wins Provide next steps
Examples
# Full analysis with validation context
/quality-analysis full-analysis path:. context:"@validation-results.json"
# Full analysis generating HTML report
/quality-analysis full-analysis path:. format:html output:quality-report.html
# Full analysis with JSON output
/quality-analysis full-analysis path:. context:"@results.json" format:json output:analysis.json
# Basic full analysis (no prior context)
/quality-analysis full-analysis path:.
Error Handling
- Missing path: Request target path parameter
- Invalid context file: Continue with limited data, show warning
- Script execution failures: Show which operation failed, provide fallback
- Output write errors: Fall back to stdout with warning
- No issues found: Congratulate on perfect quality, skip issue operations
Output Format
Terminal Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMPREHENSIVE QUALITY ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: /path/to/plugin
Type: Claude Code Plugin
Analyzed: 2025-10-13 14:30:00
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
QUALITY SCORE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
85/100 ⭐⭐⭐⭐ (Good)
Publication Ready: With Minor Changes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ISSUES SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Critical (P0): 0 ✅
Important (P1): 3 ⚠️
Recommended (P2): 5 💡
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EXECUTIVE SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Your plugin is nearly ready for publication! No critical blockers
found. Address 3 important issues to reach excellent status (90+).
Quality foundation is solid with good documentation and security.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOP QUICK WINS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. [+10 pts] Add CHANGELOG.md (15 minutes)
Impact: Improves version tracking
Fix: Create CHANGELOG.md with version history
2. [+3 pts] Add 2 more keywords (5 minutes)
Impact: Better discoverability
Fix: Add relevant keywords to plugin.json
3. [+2 pts] Add repository URL (2 minutes)
Impact: Professional appearance
Fix: Add repository field to plugin.json
After Quick Wins: 100/100 ⭐⭐⭐⭐⭐ (Excellent)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DETAILED REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Full report saved to: quality-report.md
Next Steps:
1. Review detailed report for all findings
2. Implement quick wins (22 minutes total)
3. Re-run validation to verify improvements
4. Submit to OpenPlugins marketplace
Questions? Consult: docs.claude.com/plugins
Integration Notes
This operation is the primary entry point for complete quality assessment.
Invoked by:
validation-orchestratorafter comprehensive validationmarketplace-validatoragent for submission readiness- Direct user invocation for full assessment
Orchestrates:
calculate-score.md- Quality scoringprioritize-issues.md- Issue categorizationsuggest-improvements.md- Actionable recommendationsgenerate-report.md- Comprehensive reporting
Data Flow:
Validation Results
↓
Calculate Score → score, rating, stars
↓
Prioritize Issues → P0/P1/P2 categorization
↓
Suggest Improvements → actionable recommendations
↓
Generate Report → formatted comprehensive report
↓
Display Summary → user-friendly terminal output
Performance
- Execution Time: 2-5 seconds (depending on issue count)
- I/O Operations: Minimal (uses temporary files for large datasets)
- Memory Usage: Low (streaming JSON processing)
- Parallelization: Sequential (each step depends on previous)
Quality Assurance
Validation Steps:
- Verify all scripts are executable
- Check Python 3.6+ availability
- Validate JSON context format
- Verify write permissions for output
- Ensure scoring algorithm consistency
Testing:
# Test with perfect plugin
/quality-analysis full-analysis path:./test-fixtures/perfect-plugin
# Test with issues
/quality-analysis full-analysis path:./test-fixtures/needs-work
# Test report formats
/quality-analysis full-analysis path:. format:json
/quality-analysis full-analysis path:. format:html
/quality-analysis full-analysis path:. format:markdown
Request: $ARGUMENTS
Operation: Generate Quality Report
Generate comprehensive quality report in multiple formats (markdown, JSON, HTML) with detailed findings and recommendations.
Parameters from $ARGUMENTS
Extract these parameters from $ARGUMENTS:
- path: Target path to analyze (required)
- format: Output format - markdown|json|html (default: markdown)
- output: Output file path (optional, defaults to stdout)
- context: Path to validation context JSON file with prior results (optional)
Report Structure
1. Executive Summary
- Overall quality score and star rating
- Publication readiness determination
- Key findings at-a-glance
- Critical blockers (if any)
2. Validation Layers
- Schema validation results (pass/fail with details)
- Security scan results (vulnerabilities found)
- Documentation quality assessment
- Best practices compliance check
3. Issues Breakdown
- Priority 0 (Critical): Must fix before publication
- Priority 1 (Important): Should fix for quality
- Priority 2 (Recommended): Nice to have improvements
4. Improvement Roadmap
- Prioritized action items with effort estimates
- Expected score improvement per fix
- Timeline to reach publication-ready (90+ score)
5. Detailed Findings
- Full validation output from each layer
- Code examples and fix suggestions
- References to best practices documentation
Workflow
-
Load Validation Context
IF context parameter provided: Read validation results from context file ELSE: Use current validation state Extract: - Quality score - Validation layer results - Issue lists - Target metadata -
Generate Report Sections
Execute .scripts/report-generator.py with: - Path to target - Format (markdown|json|html) - Validation context data - Output destination Script generates: - Executive summary - Validation layer breakdown - Prioritized issues - Improvement suggestions - Detailed findings -
Format Output
IF output parameter specified: Write report to file Display confirmation with file path ELSE: Print report to stdout -
Display Summary
Show brief summary: - Report generated successfully - Format used - Output location (if file) - Key metrics (score, issues)
Examples
# Generate markdown report to stdout
/quality-analysis report path:. format:markdown
# Generate JSON report to file
/quality-analysis report path:. format:json output:quality-report.json
# Generate HTML report with context
/quality-analysis report path:. format:html context:"@validation-results.json" output:report.html
# Quick markdown report from validation results
/quality-analysis report path:. context:"@comprehensive-validation.json"
Error Handling
- Missing path: Request target path
- Invalid format: List supported formats (markdown, json, html)
- Context file not found: Continue with limited data, warn user
- Invalid JSON context: Show parsing error, suggest validation
- Write permission denied: Show error, suggest alternative output location
- Python not available: Fallback to basic text report
Output Format
Markdown Report:
# Quality Assessment Report
Generated: 2025-10-13 14:30:00
Target: /path/to/plugin
Type: Claude Code Plugin
## Executive Summary
**Quality Score**: 85/100 ⭐⭐⭐⭐ (Good)
**Publication Ready**: With Minor Changes
**Critical Issues**: 0
**Total Issues**: 8
Your plugin is nearly ready for publication! Address 3 important issues to reach excellent status.
## Validation Results
### Schema Validation ✅ PASS
- All required fields present
- Valid JSON syntax
- Correct semver format
### Security Scan ✅ PASS
- No secrets exposed
- All URLs use HTTPS
- File permissions correct
### Documentation ⚠️ WARNINGS (3 issues)
- Missing CHANGELOG.md (-10 pts)
- README could use 2 more examples (-5 pts)
- No architecture documentation
### Best Practices ✅ PASS
- Naming convention correct
- Keywords appropriate (5/7)
- Category properly set
## Issues Breakdown
### Priority 0 (Critical): 0 issues
None - excellent!
### Priority 1 (Important): 3 issues
#### 1. Add CHANGELOG.md [+10 pts]
Missing version history and change documentation.
**Impact**: -10 quality score
**Effort**: Low (15 minutes)
**Fix**: Create CHANGELOG.md following Keep a Changelog format
```bash
# Create changelog
cat > CHANGELOG.md <<EOF
# Changelog
## [1.0.0] - 2025-10-13
### Added
- Initial release
EOF
2. Expand README examples [+5 pts]
README has only 1 example, recommend 3-5 examples.
Impact: Poor user onboarding, -5 score Effort: Medium (30 minutes) Fix: Add 2-4 more usage examples showing different scenarios
3. Add 2 more keywords [+3 pts]
Current: 5 keywords. Optimal: 7 keywords.
Impact: Reduced discoverability Effort: Low (5 minutes) Fix: Add relevant keywords to plugin.json
Priority 2 (Recommended): 5 issues
[Details of nice-to-have improvements...]
Improvement Roadmap
Path to Excellent (90+)
Current: 85/100 Target: 90/100 Gap: 5 points
Quick Wins (Total: +8 pts, 20 minutes)
- Add CHANGELOG.md → +10 pts (15 min)
- Add 2 keywords → +3 pts (5 min)
This Week (Total: +5 pts, 30 minutes) 3. Expand README examples → +5 pts (30 min)
After completion: 98/100 ⭐⭐⭐⭐⭐ (Excellent)
Detailed Findings
[Complete validation output from all layers...]
Report generated by marketplace-validator-plugin v1.0.0
**JSON Report**:
```json
{
"metadata": {
"generated": "2025-10-13T14:30:00Z",
"target": "/path/to/plugin",
"type": "plugin",
"validator_version": "1.0.0"
},
"executive_summary": {
"score": 85,
"rating": "Good",
"stars": "⭐⭐⭐⭐",
"publication_ready": "With Minor Changes",
"critical_issues": 0,
"total_issues": 8
},
"validation_layers": {
"schema": {"status": "pass", "issues": []},
"security": {"status": "pass", "issues": []},
"documentation": {"status": "warnings", "issues": [...]},
"best_practices": {"status": "pass", "issues": []}
},
"issues": {
"p0": [],
"p1": [...],
"p2": [...]
},
"improvement_roadmap": {
"current_score": 85,
"target_score": 90,
"gap": 5,
"recommendations": [...]
}
}
HTML Report:
<!DOCTYPE html>
<html>
<head>
<title>Quality Assessment Report</title>
<style>
/* Styled, responsive HTML report */
</style>
</head>
<body>
<!-- Executive summary card -->
<!-- Validation layer status badges -->
<!-- Interactive issue accordion -->
<!-- Improvement roadmap timeline -->
</body>
</html>
Integration Notes
This operation is invoked by:
full-analysis.mdas final step to consolidate resultsvalidation-orchestratorfor comprehensive reporting- Direct user invocation for custom reports
The report aggregates data from:
calculate-score.mdoutputprioritize-issues.mdcategorizationsuggest-improvements.mdrecommendations- All validation layer results
Request: $ARGUMENTS
Operation: Prioritize Issues
Categorize and prioritize validation issues by severity and impact using P0/P1/P2 tier system.
Parameters from $ARGUMENTS
Extract these parameters from $ARGUMENTS:
- issues: Path to JSON file with issues or inline JSON string (required)
- criteria: Prioritization criteria - severity|impact|effort (default: severity)
Prioritization Tiers
Priority 0 (P0) - Critical - Must Fix
- Invalid JSON syntax (blocks parsing)
- Missing required fields (name, version, description, author, license)
- Security vulnerabilities (exposed secrets, dangerous patterns)
- Format violations (invalid semver, malformed URLs)
- Blocks: Publication and installation
Priority 1 (P1) - Important - Should Fix
- Missing recommended fields (repository, homepage, keywords)
- Documentation gaps (incomplete README, missing CHANGELOG)
- Convention violations (naming, structure)
- Performance issues (slow scripts, inefficient patterns)
- Impact: Reduces quality score significantly
Priority 2 (P2) - Recommended - Nice to Have
- Additional keywords for discoverability
- Enhanced examples and documentation
- Expanded test coverage
- Quality improvements and polish
- Impact: Minor quality score boost
Workflow
-
Parse Issue Data
IF issues parameter starts with "@": Read JSON from file (remove @ prefix) ELSE IF issues is valid JSON: Parse inline JSON ELSE: Error: Invalid issues format -
Categorize Issues
Execute .scripts/issue-prioritizer.sh with issues data Categorize each issue based on: - Severity (critical, important, recommended) - Impact on publication readiness - Blocking status - Effort to fix -
Sort and Format
Group issues by priority (P0, P1, P2) Sort within each priority by impact Format with appropriate icons: - P0: ❌ (red X - blocking) - P1: ⚠️ (warning - should fix) - P2: 💡 (lightbulb - suggestion) -
Generate Summary
Count issues per priority Calculate total fix effort Estimate score improvement potential
Examples
# Prioritize from validation results file
/quality-analysis prioritize issues:"@validation-results.json"
# Prioritize inline JSON
/quality-analysis prioritize issues:'{"errors": [{"type": "missing_field", "field": "license"}]}'
# Prioritize with impact criteria
/quality-analysis prioritize issues:"@results.json" criteria:impact
Error Handling
- Missing issues parameter: Request issues data
- Invalid JSON format: Show JSON parsing error with line number
- Empty issues array: Return "No issues found" message
- File not found: Show file path and suggest correct path
- Script execution error: Fallback to basic categorization
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ISSUE PRIORITIZATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Issues: <count>
Estimated Fix Time: <time>
Priority 0 (Critical - Must Fix): <count>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Missing required field: license
Impact: Blocks publication
Effort: Low (5 minutes)
Fix: Add "license": "MIT" to plugin.json
❌ Invalid JSON syntax at line 23
Impact: Blocks parsing
Effort: Low (2 minutes)
Fix: Remove trailing comma
Priority 1 (Important - Should Fix): <count>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ Missing CHANGELOG.md
Impact: -10 quality score
Effort: Low (15 minutes)
Fix: Create CHANGELOG.md following Keep a Changelog format
⚠️ README missing usage examples
Impact: Poor user experience, -5 score
Effort: Medium (30 minutes)
Fix: Add 3-5 usage examples to README
Priority 2 (Recommended - Nice to Have): <count>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 Add 2 more keywords for discoverability
Impact: +3 quality score
Effort: Low (5 minutes)
Fix: Add relevant keywords to plugin.json
💡 Expand documentation with architecture diagram
Impact: Better understanding, +2 score
Effort: Medium (45 minutes)
Fix: Create docs/ARCHITECTURE.md with diagram
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary:
- Fix P0 issues first (blocking)
- Address P1 issues for quality (30-60 min)
- Consider P2 improvements for excellence
- Total potential score gain: +20 points
Issue Data Schema
Expected JSON structure:
{
"errors": [
{
"type": "missing_field|invalid_format|security",
"severity": "critical|important|recommended",
"field": "field_name",
"message": "Description",
"location": "file:line",
"fix": "How to fix",
"effort": "low|medium|high",
"score_impact": 20
}
],
"warnings": [...],
"recommendations": [...]
}
Integration Notes
This operation is invoked by:
full-analysis.mdafter score calculationvalidation-orchestratorfor issue triage- Direct user invocation for issue planning
Request: $ARGUMENTS
You are the Quality Analysis coordinator, responsible for comprehensive quality assessment and scoring.
Your Mission
Parse $ARGUMENTS to determine the requested quality analysis operation and route to the appropriate sub-command.
Available Operations
Parse the first word of $ARGUMENTS to determine which operation to execute:
- score → Read
.claude/commands/quality-analysis/calculate-score.md - report → Read
.claude/commands/quality-analysis/generate-report.md - prioritize → Read
.claude/commands/quality-analysis/prioritize-issues.md - improve → Read
.claude/commands/quality-analysis/suggest-improvements.md - full-analysis → Read
.claude/commands/quality-analysis/full-analysis.md
Argument Format
/quality-analysis <operation> [parameters]
Examples
# Calculate quality score
/quality-analysis score path:. errors:2 warnings:5 missing:3
# Generate comprehensive report
/quality-analysis report path:. format:markdown
# Prioritize issues by severity
/quality-analysis prioritize issues:"@validation-results.json"
# Get improvement suggestions
/quality-analysis improve path:. score:65
# Run full quality analysis
/quality-analysis full-analysis path:. context:"@validation-context.json"
Quality Scoring System
This skill implements the OpenPlugins quality scoring system:
- 90-100: Excellent ⭐⭐⭐⭐⭐ (publication-ready)
- 75-89: Good ⭐⭐⭐⭐ (ready with minor improvements)
- 60-74: Fair ⭐⭐⭐ (needs work)
- 40-59: Needs Improvement ⭐⭐
- 0-39: Poor ⭐ (substantial work needed)
Error Handling
If the operation is not recognized:
- List all available operations
- Show example usage
- Suggest closest match
Base Directory
Base directory for this skill: .claude/commands/quality-analysis/
Your Task
- Parse
$ARGUMENTSto extract operation and parameters - Read the corresponding operation file
- Execute quality analysis with provided parameters
- Return actionable results with clear recommendations
Current Request: $ARGUMENTS
Operation: Suggest Improvements
Generate actionable improvement suggestions based on current quality score with effort estimates and expected impact.
Parameters from $ARGUMENTS
Extract these parameters from $ARGUMENTS:
- path: Target path to analyze (required)
- score: Current quality score (required)
- target: Target score to achieve (default: 90)
- context: Path to validation context JSON file (optional)
Improvement Suggestion Algorithm
gap = target_score - current_score
improvements_needed = ceiling(gap / 5) # Approximate improvements needed
FOR each validation layer:
IF layer has issues:
Generate specific, actionable improvements
Estimate score impact (+points)
Assign priority based on blocking status and impact
Estimate effort (low/medium/high)
SORT by:
1. Priority (P0 first)
2. Score impact (highest first)
3. Effort (lowest first - quick wins)
LIMIT to top 10 most impactful improvements
Workflow
-
Calculate Score Gap
gap = target - current_score IF gap <= 0: Return "Already at or above target!" IF gap <= 5: Focus on quick wins (low effort, high impact) IF gap > 20: Focus on critical issues first -
Analyze Validation Context
IF context provided: Load validation results from JSON file Extract issues from each layer: - Schema validation issues - Security scan findings - Documentation gaps - Best practices violations Categorize by: - Severity (P0/P1/P2) - Score impact - Effort required -
Generate Improvement Suggestions
For each issue, create suggestion: - Title (brief, actionable) - Score impact (+X points) - Priority (High/Medium/Low) - Effort estimate with time - Detailed fix instructions - Expected outcome Sort by effectiveness: effectiveness = score_impact / effort_hours -
Create Improvement Roadmap
Group suggestions into phases: - Quick Wins (< 30 min, +5-15 pts) - This Week (< 2 hours, +10-20 pts) - This Sprint (< 1 day, +20+ pts) Calculate cumulative score after each phase
Examples
# Get improvements for low score
/quality-analysis improve path:. score:65
# Target excellent status
/quality-analysis improve path:. score:78 target:95
# Use validation context for detailed suggestions
/quality-analysis improve path:. score:70 context:"@validation-results.json"
Error Handling
- Missing score: Request current score or run calculate-score first
- Invalid score range: Score must be 0-100
- Invalid target: Target must be higher than current score
- Context file not found: Continue with basic suggestions
- No improvements possible: Congratulate on perfect score
Output Format
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
IMPROVEMENT RECOMMENDATIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Current Score: 65/100 ⭐⭐⭐ (Fair)
Target Score: 90/100 ⭐⭐⭐⭐⭐ (Excellent)
Gap: 25 points
To reach your target, implement these improvements:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
QUICK WINS (Total: +15 pts, 45 minutes)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. [+10 pts] Add CHANGELOG.md with version history
Priority: High
Effort: Low (15 minutes)
Impact: Improves version tracking and transparency
HOW TO FIX:
```bash
cat > CHANGELOG.md <<'EOF'
# Changelog
All notable changes to this project will be documented in this file.
## [1.0.0] - 2025-10-13
### Added
- Initial release
- Core functionality
EOF
WHY IT MATTERS: Users need to track changes between versions. CHANGELOG.md is a best practice for professional plugins.
-
[+3 pts] Add 2 more relevant keywords to plugin.json Priority: Medium Effort: Low (5 minutes) Impact: Improved discoverability in marketplace
HOW TO FIX:
{ "keywords": ["existing", "keywords", "automation", "workflow"] }SUGGESTION: Based on your plugin's functionality, consider:
- "automation" (if you automate tasks)
- "productivity" (if you improve efficiency)
- "validation" (if you validate data)
-
[+2 pts] Add repository URL to plugin.json Priority: Medium Effort: Low (2 minutes) Impact: Users can view source and report issues
HOW TO FIX:
{ "repository": { "type": "git", "url": "https://github.com/username/plugin-name" } }
After Quick Wins: 80/100 ⭐⭐⭐⭐ (Good)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ THIS WEEK (Total: +12 pts, 90 minutes) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
[+5 pts] Expand README with 3 more usage examples Priority: Medium Effort: Medium (30 minutes) Impact: Better user onboarding and adoption
HOW TO FIX: Add examples showing:
- Basic usage (simple case)
- Advanced usage (complex scenario)
- Common workflows (real-world use)
- Error handling (what to do when things fail)
TEMPLATE:
## Examples ### Basic Usage /your-command simple-task ### Advanced Usage /your-command complex-task param:value ### Common Workflow 1. /your-command init 2. /your-command process 3. /your-command finalize -
[+5 pts] Add homepage URL to plugin.json Priority: Low Effort: Low (5 minutes) Impact: Professional appearance, marketing
HOW TO FIX:
{ "homepage": "https://your-plugin-docs.com" } -
[+2 pts] Improve description in plugin.json Priority: Low Effort: Medium (10 minutes) Impact: Better first impression in marketplace
HOW TO FIX: Make description:
- Concise (1-2 sentences)
- Action-oriented (starts with verb)
- Benefit-focused (what user gains)
BEFORE: "A plugin for validation" AFTER: "Automatically validate your code quality with comprehensive checks for security, performance, and best practices"
After This Week: 92/100 ⭐⭐⭐⭐⭐ (Excellent)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Path to Excellence:
- Start with Quick Wins (45 min) → 80/100 ⭐⭐⭐⭐
- Complete This Week items (90 min) → 92/100 ⭐⭐⭐⭐⭐
- Total effort: 2 hours 15 minutes
- Total improvement: +27 points
Priority Order:
- Fix P0 blockers (none currently)
- Implement quick wins for fast progress
- Address documentation improvements
- Polish with recommended enhancements
Your plugin will be publication-ready after Quick Wins! Excellence status achievable within one week.
### Improvement Categories
**Documentation**
- Add/expand README
- Create CHANGELOG.md
- Add LICENSE file
- Include usage examples
- Add architecture documentation
**Metadata**
- Add repository URL
- Add homepage URL
- Expand keywords (3-7 recommended)
- Improve description
- Add author details
**Code Quality**
- Fix naming conventions
- Improve error handling
- Add input validation
- Optimize performance
- Remove code smells
**Security**
- Remove exposed secrets
- Validate user input
- Use HTTPS for all URLs
- Set correct file permissions
- Add security documentation
**Best Practices**
- Follow semantic versioning
- Use lowercase-hyphen naming
- Select appropriate category
- Include test coverage
- Add CI/CD configuration
### Integration Notes
This operation is invoked by:
- `full-analysis.md` to provide actionable next steps
- `validation-orchestrator` after comprehensive validation
- Direct user invocation for improvement planning
Suggestions are based on:
- Current quality score and target
- Validation layer findings
- Industry best practices
- Effort vs impact analysis
**Request**: $ARGUMENTS
Operation: Check Plugin Entries
Validate plugin entries in marketplace configuration for completeness and format compliance.
Parameters from $ARGUMENTS
- marketplace: Path to marketplace.json file (required)
- strict: Require all recommended fields in plugin entries (optional, default: false)
- index: Validate specific plugin entry by index (optional, validates all if not specified)
Workflow
-
Load Marketplace Configuration
Locate marketplace.json: - Direct path: <marketplace> - Relative: <marketplace>/marketplace.json - Claude plugin: <marketplace>/.claude-plugin/marketplace.json Validate JSON syntax first -
Extract Plugin Entries
Parse plugins array from marketplace.json Count total entries Determine which entries to validate (all or specific index) -
Validate Each Plugin Entry
For each plugin entry, execute .scripts/schema-differ.sh Check required fields: - name (string, lowercase-hyphen) - source (string, valid format: ./path, github:, https://) - description (string, non-empty) Check recommended fields: - version (string, semver) - author (string or object) - keywords (array, 3-7 items) - license (string, SPDX identifier) Validate field formats: - name: lowercase-hyphen pattern - version: semantic versioning - source: valid source format - license: SPDX identifier -
Aggregate Results
Per-entry summary: - Entry index - Plugin name - Status: PASS/FAIL - Missing required fields - Missing recommended fields - Format violations Overall summary: - Total entries - Passed count - Failed count - Total issues
Plugin Entry Required Fields
name: Unique plugin identifier (lowercase-hyphen)source: Where to locate plugin (./path, github:user/repo, https://url)description: Brief plugin description (non-empty)
Plugin Entry Recommended Fields
version: Plugin version (semver)author: Plugin author (string or object)keywords: Search keywords (array of 3-7 strings)license: License identifier (SPDX)homepage: Documentation URLrepository: Source code URL
Source Format Validation
Relative Path:
- Pattern:
./or../ - Example:
./plugins/my-plugin
GitHub Format:
- Pattern:
github:owner/repo - Example:
github:anthropics/claude-plugin
Git URL:
- Pattern:
https://...git - Example:
https://github.com/user/plugin.git
Archive URL:
- Pattern:
https://....(zip|tar.gz|tgz) - Example:
https://example.com/plugin.zip
Examples
# Validate all plugin entries in marketplace
/schema-validation entries marketplace:./test-marketplace
# Validate with strict mode (require recommended fields)
/schema-validation entries marketplace:marketplace.json strict:true
# Validate specific plugin entry by index
/schema-validation entries marketplace:marketplace.json index:0
Error Handling
- Marketplace not found: Show searched paths
- Invalid JSON: Suggest running json validation
- No plugins array: Error - required field
- Empty plugins array: Warning - marketplace has no plugins
- Invalid index: Error with valid range
Output Format
Success (all entries valid):
✅ Plugin Entries Validation: PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Marketplace: ./test-marketplace/marketplace.json
Total Entries: 3
Entry 0: code-review ✅
Required (3/3):
✅ name: "code-review"
✅ source: "./plugins/code-review"
✅ description: "Automated code review..."
Recommended (4/4):
✅ version: "2.0.0"
✅ author: Present
✅ keywords: 3 items
✅ license: "MIT"
Entry 1: deploy-tools ✅
Required (3/3):
✅ name: "deploy-tools"
✅ source: "github:company/deploy"
✅ description: "Deployment automation..."
Recommended (3/4):
✅ version: "1.5.0"
✅ author: Present
⚠️ keywords: Missing
Entry 2: security-scan ✅
Required (3/3):
✅ name: "security-scan"
✅ source: "https://example.com/plugin.zip"
✅ description: "Security vulnerability scanning..."
Summary:
Total: 3 entries
Passed: 3 (100%)
Failed: 0
Warnings: 1 (non-blocking)
Status: PASS
Failure (validation errors):
❌ Plugin Entries Validation: FAIL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Marketplace: marketplace.json
Total Entries: 2
Entry 0: my-plugin ❌
Required (2/3):
❌ name: "My-Plugin"
Invalid: Must use lowercase-hyphen format
Expected: my-plugin
❌ source: Missing (REQUIRED)
✅ description: "My awesome plugin"
Recommended (1/4):
✅ version: "1.0.0"
❌ author: Missing
❌ keywords: Missing
❌ license: Missing
Issues: 5 (2 critical, 3 warnings)
Entry 1: test-tool ✅
Required (3/3):
✅ name: "test-tool"
✅ source: "./plugins/test-tool"
✅ description: "Testing utilities"
Recommended (2/4):
⚠️ version: Missing
⚠️ author: Missing
Summary:
Total: 2 entries
Passed: 1 (50%)
Failed: 1 (50%)
Critical Issues: 2
Warnings: 5
Status: FAIL
Action Required:
Fix plugin entry #0 (my-plugin):
- Change name to lowercase-hyphen: "my-plugin"
- Add source field: "./plugins/my-plugin"
- Consider adding: author, keywords, license
Empty Marketplace:
⚠️ Plugin Entries Validation: WARNING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Marketplace: marketplace.json
⚠️ No plugin entries found
- plugins array is empty
- Add at least one plugin entry to marketplace
Status: WARNING (empty marketplace)
Integration
This operation is called by:
full-schema-validation.md- When validating marketplace typevalidation-orchestrator- Marketplace comprehensive validation- Direct user invocation for plugin entry checking
Request: $ARGUMENTS
Operation: Check Required Fields
Verify all required fields are present and non-empty in plugin or marketplace configuration.
Parameters from $ARGUMENTS
- path: Path to plugin directory or marketplace file (required)
- type: Target type:
pluginormarketplace(required) - strict: Fail on missing recommended fields (optional, default: false)
Workflow
-
Detect Target Type
IF type not specified: Auto-detect based on path structure: - Has plugin.json → plugin - Has marketplace.json or .claude-plugin/marketplace.json → marketplace - Otherwise → error -
Locate Configuration File
For plugin: Check: <path>/plugin.json For marketplace: Check: <path>/marketplace.json OR: <path>/.claude-plugin/marketplace.json IF not found: Return error with searched paths -
Execute Field Validation
Execute .scripts/field-checker.sh "$config_file" "$type" "$strict" Returns: - List of required fields: present ✅ or missing ❌ - List of recommended fields: present ✅ or missing ⚠️ - Overall status: PASS or FAIL -
Aggregate Results
Count: - Required missing: critical errors - Recommended missing: warnings IF any required missing: Exit with status 1 IF strict mode AND any recommended missing: Exit with status 1 Otherwise: Exit with status 0
Required Fields by Type
Per the current Claude Code plugin manifest schema
(https://code.claude.com/docs/en/plugins-reference), name is the only truly
required field in plugin.json. All other metadata is recommended but optional.
Plugin (from .claude-plugin/plugin.json):
name(string, lowercase-hyphen format)
Marketplace (from .claude-plugin/marketplace.json):
name(string, lowercase-hyphen; not a reserved marketplace name)owner(object)owner.name(string)plugins(array, at least one entry)
Recommended Fields
Plugin:
version(string, semver X.Y.Z)description(string, 50-200 characters)author(string, or object{name, email?, url?})license(string, SPDX identifier)repository(string URL — the legacy{type, url}object form is rejected by the current Claude Code validator)homepage(string, documentation URL)keywords(array, 3-7 relevant keywords)category(string, one of 10 approved categories)
Plugin userConfig (if present, each entry requires):
type(one ofstring,number,boolean,directory,file)title(non-empty string, user-facing label)- Optional:
description,default,sensitive,required,enum
Marketplace:
owner.email(string, valid email format — optional per spec)metadata.description(string, marketplace purpose)metadata.version(string, marketplace version)metadata.homepage(string, marketplace documentation)metadata.repository(string, marketplace source)metadata.pluginRoot(string, base dir prepended to relative plugin sources)
Plugin entry (inside a marketplace plugins[] array):
- Required:
name,source - Recommended:
description,version,author,license,category,keywords sourcemay be a relative-path string ("./plugins/foo") or an object:{"source": "github", "repo": "owner/repo", "ref?": "...", "sha?": "..."}{"source": "url", "url": "...", "ref?": "...", "sha?": "..."}{"source": "git-subdir", "url": "...", "path": "...", "ref?": "...", "sha?": "..."}{"source": "npm", "package": "...", "version?": "...", "registry?": "..."}
Examples
# Check plugin required fields
/schema-validation fields path:. type:plugin
# Check marketplace with strict mode (fail on missing recommended)
/schema-validation fields path:./test-marketplace type:marketplace strict:true
# Auto-detect type
/schema-validation fields path:.
Error Handling
- File not found: List all searched paths
- Invalid JSON: Suggest running json validation first
- Unknown type: Show valid types (plugin, marketplace)
- Empty field: Report which field is present but empty
Output Format
Success (all required present):
✅ Required Fields Validation: PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: plugin.json
Type: plugin
Required Fields (5/5):
✅ name: "my-plugin"
✅ version: "1.0.0"
✅ description: "My awesome plugin"
✅ author: "Developer Name"
✅ license: "MIT"
Recommended Fields (3/4):
✅ repository: Present
✅ homepage: Present
✅ keywords: Present
⚠️ category: Missing (improves discoverability)
Status: PASS
Warnings: 1 (non-blocking)
Failure (missing required):
❌ Required Fields Validation: FAIL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: plugin.json
Type: plugin
Required Fields (3/5):
✅ name: "my-plugin"
❌ version: Missing (REQUIRED - use semver X.Y.Z)
✅ description: "My plugin"
❌ license: Missing (REQUIRED - use MIT, Apache-2.0, etc.)
✅ author: "Developer"
Critical Issues: 2
Status: FAIL
Action Required:
Add missing required fields to plugin.json:
- version: "1.0.0"
- license: "MIT"
Marketplace Example:
✅ Required Fields Validation: PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: marketplace.json
Type: marketplace
Required Fields (5/5):
✅ name: "my-marketplace"
✅ owner.name: "DevTools Team"
✅ owner.email: "devtools@example.com"
✅ plugins: Array with 3 entries
Status: PASS
Integration
This operation is called by:
full-schema-validation.md- Second validation step after JSON syntaxvalidation-orchestrator- Comprehensive validation checks- Direct user invocation for field checking
Request: $ARGUMENTS
Operation: Full Schema Validation
Execute complete schema validation workflow: JSON syntax → Required fields → Format compliance → Plugin entries (if marketplace).
Parameters from $ARGUMENTS
- path: Path to plugin directory or marketplace (required)
- type: Target type:
pluginormarketplace(optional, auto-detect) - strict: Fail on warnings and missing recommended fields (optional, default: false)
- verbose: Show detailed error information (optional, default: false)
Workflow
-
Detect Target Type
IF type not specified: Auto-detect based on path structure: - Has plugin.json at root → plugin - Has marketplace.json → marketplace - Otherwise → error Locate configuration file: Plugin: <path>/plugin.json Marketplace: <path>/marketplace.json or <path>/.claude-plugin/marketplace.json -
Phase 1: JSON Syntax Validation
Read validate-json.md instructions Execute: .scripts/json-validator.py --file "$config" --verbose "$verbose" On failure: - Report JSON syntax errors - Stop validation (cannot proceed with invalid JSON) - Exit with status 1 On success: - Continue to Phase 2 -
Phase 2: Required Fields Check
Read check-required-fields.md instructions Execute: .scripts/field-checker.sh "$config" "$type" "$strict" Collect results: - Required fields: present/missing - Recommended fields: present/missing - Critical errors count - Warnings count On failure: - Report missing required fields - Continue to Phase 3 (show all issues) On success: - Continue to Phase 3 -
Phase 3: Format Validation
Read validate-formats.md instructions Execute: .scripts/format-validator.py --file "$config" --type "$type" --strict "$strict" Validate: - Semantic versioning - Lowercase-hyphen naming - URL formats - Email addresses - License identifiers - Category names (if present) Collect results: - Format violations count - Warnings count -
Phase 4: Plugin Entries Validation (Marketplace Only)
IF type == "marketplace": Read check-plugin-entries.md instructions Execute: .scripts/schema-differ.sh "$config" "all" Validate each plugin entry: - Required fields (name, source, description) - Recommended fields (version, author, license, keywords) - Format compliance Collect results: - Total plugin entries - Passed entries - Failed entries - Total issues per entry -
Aggregate Results
Compile all validation phases: Phase 1: JSON Syntax [PASS/FAIL] Phase 2: Required Fields [PASS/FAIL] Phase 3: Format Compliance [PASS/FAIL] Phase 4: Plugin Entries [PASS/FAIL] (marketplace only) Calculate overall status: IF any phase FAIL: Overall FAIL IF strict mode AND any warnings: Overall FAIL ELSE: Overall PASS Generate summary report: - Total checks performed - Critical errors - Warnings - Overall status - Publication readiness
Exit Codes
- 0: All validation passed (or warnings only in non-strict mode)
- 1: Validation failed (critical errors or strict mode with warnings)
- 2: Error (file not found, invalid arguments, etc.)
Examples
# Full validation with auto-detect
/schema-validation full-schema path:.
# Full plugin validation with strict mode
/schema-validation full-schema path:. type:plugin strict:true
# Full marketplace validation with verbose output
/schema-validation full-schema path:./test-marketplace type:marketplace verbose:true
# Validate specific plugin in subdirectory
/schema-validation full-schema path:./plugins/my-plugin type:plugin
Integration
This operation is the primary entry point for complete schema validation and is called by:
validation-orchestratorcomprehensive validation- Marketplace submission workflows
- CI/CD validation pipelines
- Direct user invocation for thorough checking
Output Format
Success (all phases pass):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FULL SCHEMA VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: plugin.json
Type: plugin
Mode: Standard
Phase 1: JSON Syntax ✅
Status: Valid JSON
Backend: jq
Phase 2: Required Fields ✅
Required: 5/5 present
Recommended: 3/4 present
Missing: category (non-critical)
Phase 3: Format Compliance ✅
Checks: 7/7 passed
Version: 1.0.0 (valid semver)
Name: my-plugin (valid lowercase-hyphen)
License: MIT (valid SPDX)
URLs: All valid HTTPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Status: ✅ PASS
Checks Performed: 15
Critical Errors: 0
Warnings: 1
Passed: 14
Publication Readiness: READY ✅
Your plugin meets all required standards
Consider adding: category field for better discoverability
Quality Score: 95/100 ⭐⭐⭐⭐⭐
Failure (multiple phases fail):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FULL SCHEMA VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: plugin.json
Type: plugin
Mode: Standard
Phase 1: JSON Syntax ✅
Status: Valid JSON
Backend: python3
Phase 2: Required Fields ❌
Required: 3/5 present
Missing:
❌ version (REQUIRED - use semver X.Y.Z)
❌ license (REQUIRED - use MIT, Apache-2.0, etc.)
Phase 3: Format Compliance ❌
Checks: 4/6 passed
Violations:
❌ name: "My-Plugin" - must use lowercase-hyphen
❌ homepage: "example.com" - must be valid URL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Status: ❌ FAIL
Checks Performed: 11
Critical Errors: 4
Warnings: 0
Passed: 7
Publication Readiness: NOT READY ❌
Fix 4 critical issues before submission
Priority Actions:
1. Add version field: "1.0.0"
2. Add license field: "MIT"
3. Fix name format: "my-plugin"
4. Fix homepage URL: "https://example.com"
Quality Score: 45/100 ⭐⭐
Rating: Needs Improvement
Next Steps:
1. Fix all critical errors above
2. Re-run validation: /schema-validation full-schema path:.
3. Aim for quality score 90+ for publication
Marketplace Example (with plugin entries):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FULL SCHEMA VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: marketplace.json
Type: marketplace
Mode: Standard
Phase 1: JSON Syntax ✅
Status: Valid JSON
Phase 2: Required Fields ✅
Required: 5/5 present
Recommended: 4/4 present
Phase 3: Format Compliance ✅
Checks: 4/4 passed
Phase 4: Plugin Entries ✅
Total Entries: 3
Passed: 3 (100%)
Failed: 0
Entry 0: code-review ✅
Entry 1: deploy-tools ✅
Entry 2: security-scan ✅
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Status: ✅ PASS
Checks Performed: 23
Critical Errors: 0
Warnings: 0
Passed: 23
Publication Readiness: READY ✅
Your marketplace meets all standards
All 3 plugin entries are valid
Quality Score: 100/100 ⭐⭐⭐⭐⭐
Rating: Excellent
Error Handling
- File not found: List searched paths, suggest creating configuration
- Invalid JSON: Stop at Phase 1, show syntax errors
- Auto-detect failure: Suggest specifying type explicitly
- Script execution error: Show script path and error message
Performance
- Plugin: 1-2 seconds (3 phases)
- Marketplace: 2-5 seconds (4 phases, depends on plugin entry count)
- Large Marketplace: 5-10 seconds (50+ plugin entries)
Request: $ARGUMENTS
You are the Schema Validation coordinator, ensuring structural integrity and format compliance.
Your Mission
Parse $ARGUMENTS to determine the requested schema validation operation and route to the appropriate sub-command.
Available Operations
Parse the first word of $ARGUMENTS to determine which operation to execute:
- json → Read
.claude/commands/schema-validation/validate-json.md - fields → Read
.claude/commands/schema-validation/check-required-fields.md - formats → Read
.claude/commands/schema-validation/validate-formats.md - entries → Read
.claude/commands/schema-validation/check-plugin-entries.md - full-schema → Read
.claude/commands/schema-validation/full-schema-validation.md
Argument Format
/schema-validation <operation> [parameters]
Examples
# Validate JSON syntax
/schema-validation json file:plugin.json
# Check required fields
/schema-validation fields path:. type:plugin
# Validate formats (semver, URLs, naming)
/schema-validation formats path:.
# Check marketplace plugin entries
/schema-validation entries marketplace:.claude-plugin/marketplace.json
# Run complete schema validation
/schema-validation full-schema path:. type:plugin
Validation Scope
For Plugins:
- Required: name, version, description, author, license
- Formats: semver (version), lowercase-hyphen (name), valid license
- Optional: keywords, category, homepage, repository
For Marketplaces:
- Required: name, owner, plugins
- Plugin entries: name, version, source, description, author, license
- Formats: valid source (github:, URL, path)
Error Handling
If the operation is not recognized:
- List all available operations
- Show validation scope
- Provide usage examples
Base Directory
Base directory for this skill: .claude/commands/schema-validation/
Your Task
- Parse
$ARGUMENTSto extract operation and parameters - Read the corresponding operation file
- Execute schema validation with multi-backend support (jq, python3)
- Return detailed validation results with line numbers for errors
Current Request: $ARGUMENTS
Operation: Validate Formats
Validate format compliance for semver, URLs, email addresses, and naming conventions.
Parameters from $ARGUMENTS
- path: Path to plugin directory or marketplace file (required)
- type: Target type:
pluginormarketplace(optional, auto-detect) - strict: Enforce HTTPS for all URLs (optional, default: false)
Workflow
-
Locate Configuration File
Auto-detect or use specified type: Plugin: plugin.json Marketplace: marketplace.json or .claude-plugin/marketplace.json -
Execute Format Validation
Execute .scripts/format-validator.py --file "$config" --type "$type" --strict "$strict" Validates: - Semantic versioning (X.Y.Z) - Lowercase-hyphen naming (^[a-z0-9]+(-[a-z0-9]+)*$) - URL formats (http/https) - Email addresses (RFC 5322 compliant) - License identifiers (SPDX) - Category names (10 approved categories) -
Report Results
For each field: ✅ Valid format ❌ Invalid format with specific error and remediation Summary: - Total fields checked - Passed count - Failed count - Exit code: 0 (all pass) or 1 (any fail)
Format Validation Rules
Semantic Versioning (version field):
- Pattern:
X.Y.Zwith optional pre-release/build metadata - Valid:
1.0.0,2.5.3,10.20.30,1.0.0-beta,1.0.0+build.123 - Invalid:
1.0,v1.0.0
Lowercase-Hyphen Naming (name field):
- Pattern:
^[a-z0-9]+(-[a-z0-9]+)*$ - Valid:
my-plugin,test-marketplace,plugin123 - Invalid:
My-Plugin,test_plugin,plugin.name,-plugin,plugin-
URL Format (homepage, repository fields):
- Must be a string URL starting with
http://orhttps:// - The legacy
{"type": "git", "url": "..."}object form forrepositoryis rejected by the current Claude Code validator — use a plain string URL. - Strict mode: Only
https://allowed - Valid:
https://example.com,http://localhost:3000 - Invalid:
example.com,www.example.com,ftp://example.com,{"type": "git", "url": "..."}(legacy object form)
Email Format (owner.email, author.email fields):
- RFC 5322 compliant pattern
- Valid:
user@example.com,name.surname@company.co.uk - Invalid:
user@,@example.com,user example.com
License Identifier (license field):
- SPDX identifier or "Proprietary"
- Common: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause
- Valid:
MIT,Apache-2.0,ISC,Proprietary - Invalid:
mit,Apache 2.0,BSD
Category (category field):
- One of 10 approved categories
- Valid: development, testing, deployment, documentation, security, database, monitoring, productivity, quality, collaboration
- Invalid: coding, devops, tools, utilities
Examples
# Validate plugin formats
/schema-validation formats path:.
# Validate marketplace with strict HTTPS enforcement
/schema-validation formats path:./test-marketplace type:marketplace strict:true
# Validate specific plugin
/schema-validation formats path:./my-plugin type:plugin
Error Handling
- File not found: Show expected locations
- Invalid JSON: Suggest running json validation first
- Format violation: Specific error with correct pattern
- Unknown field: Warn but don't fail
Output Format
Success (all formats valid):
✅ Format Validation: PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: plugin.json
Type: plugin
Format Checks (7/7):
✅ name: "my-plugin" (lowercase-hyphen)
✅ version: "1.0.0" (semver)
✅ description: Valid length (73 chars)
✅ license: "MIT" (SPDX identifier)
✅ homepage: "https://example.com" (valid URL)
✅ repository: "https://github.com/user/repo" (valid URL)
✅ category: "development" (approved category)
Status: PASS
Failure (format violations):
❌ Format Validation: FAIL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: plugin.json
Type: plugin
Format Checks (4/7):
❌ name: "My-Plugin"
Invalid: Must use lowercase-hyphen format
Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
Example: my-plugin, test-tool, plugin123
❌ version: "1.0"
Invalid: Must use semantic versioning (X.Y.Z)
Expected: Three version numbers separated by dots
Example: 1.0.0, 2.1.5
✅ description: Valid (80 characters)
❌ license: "Apache 2.0"
Invalid: Must be SPDX identifier
Expected: Apache-2.0
Valid identifiers: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause
⚠️ homepage: "http://example.com"
Warning: Consider using HTTPS for security
Current: http://example.com
Recommended: https://example.com
✅ repository: "https://github.com/user/repo"
❌ category: "coding"
Invalid: Must be one of 10 approved categories
Valid: development, testing, deployment, documentation,
security, database, monitoring, productivity,
quality, collaboration
Failed: 4
Warnings: 1
Status: FAIL
Action Required:
Fix format violations:
- name: Convert to lowercase-hyphen (my-plugin)
- version: Use semver format (1.0.0)
- license: Use SPDX identifier (Apache-2.0)
- category: Choose approved category (development)
Marketplace Example:
✅ Format Validation: PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: marketplace.json
Type: marketplace
Format Checks (4/4):
✅ name: "enterprise-marketplace" (lowercase-hyphen)
✅ owner.email: "devtools@company.com" (valid email)
✅ metadata.homepage: "https://company.com/plugins" (valid HTTPS URL)
✅ metadata.repository: "https://github.com/company/plugins" (valid HTTPS URL)
Status: PASS
Strict HTTPS: Enforced ✅
Integration
This operation is called by:
full-schema-validation.md- Third validation step after fields checkbest-practicesskill - Naming and versioning validation- Direct user invocation for format checking
Request: $ARGUMENTS
Operation: Validate JSON Syntax
Validate JSON file syntax with multi-backend support (jq + python3 fallback).
Parameters from $ARGUMENTS
- file: Path to JSON file (required)
- verbose: Show detailed error information (optional, default: false)
Workflow
-
Parse Arguments
Extract file path from $ARGUMENTS Check if verbose mode requested -
Validate File Exists
IF file does not exist: Return error with file path Exit with status 1 -
Detect JSON Tool
Execute .scripts/json-validator.py --detect Primary: jq (faster, better error messages) Fallback: python3 (universal availability) -
Validate JSON Syntax
Execute .scripts/json-validator.py --file "$file" --verbose "$verbose" On success: - Print success message with file path - Return 0 On failure: - Print error message with line number and details - Show problematic JSON section - Return 1
Examples
# Basic JSON validation
/schema-validation json file:plugin.json
# Verbose validation with details
/schema-validation json file:marketplace.json verbose:true
# Validate multiple files (call multiple times)
/schema-validation json file:plugin1.json
/schema-validation json file:plugin2.json
Error Handling
- File not found: Clear message with expected path
- Invalid JSON: Line number, character position, error description
- No JSON tool available: Instruction to install jq or python3
- Permission denied: File access error with remediation
Output Format
Success:
✅ Valid JSON: plugin.json
Backend: jq
Failure (basic):
❌ Invalid JSON: marketplace.json
Error: Unexpected token at line 15
Failure (verbose):
❌ Invalid JSON: marketplace.json
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Error Details:
Line: 15
Position: 8
Issue: Expected ',' or ']' but got '}'
Problematic Section (lines 13-17):
13 | "plugins": [
14 | {
15 | "name": "test"
16 | }
17 | }
Remediation:
- Check for missing commas between array elements
- Verify bracket matching: [ ] { }
- Use a JSON formatter/linter in your editor
Integration
This operation is called by:
full-schema-validation.md- First validation stepvalidation-orchestrator- Quick validation checks- Direct user invocation for single file checks
Request: $ARGUMENTS
Operation: Check File Permissions
Audit file permissions to detect world-writable files, overly permissive scripts, and inappropriate executability.
Parameters from $ARGUMENTS
- path: Target directory to scan (required)
- strict: Enforce strict permission rules (true|false, default: false)
- check-executables: Verify executable files have shebangs (true|false, default: true)
- report-all: Report all permissions, not just issues (true|false, default: false)
Permission Rules
Forbidden Permissions (CRITICAL):
-
777 (rwxrwxrwx) - World-writable and executable
- Risk: Anyone can modify and execute
- Remediation: chmod 755 (directories) or 644 (files)
-
666 (rw-rw-rw-) - World-writable files
- Risk: Anyone can modify content
- Remediation: chmod 644 (owner write, others read)
-
000 (---------) - Inaccessible files
- Risk: Unusable file, potential error
- Remediation: chmod 644 or remove
Scripts & Executables (HIGH priority):
-
Shell scripts (*.sh, *.bash) SHOULD be:
- 755 (rwxr-xr-x) or 750 (rwxr-x---)
- Have shebang (#!/bin/bash, #!/usr/bin/env bash)
- Not world-writable
-
Python scripts (*.py) SHOULD be:
- 755 if executable, 644 if library
- Have shebang if executable (#!/usr/bin/env python3)
-
Node.js scripts (*.js, *.ts) SHOULD be:
- 644 (not executable, run via node)
- Exception: CLI tools can be 755 with shebang
Configuration Files (MEDIUM priority):
-
Config files (.env, *.json, *.yaml, *.conf) SHOULD be:
- 600 (rw-------) for sensitive configs
- 644 (rw-r--r--) for non-sensitive
- Never 666 or 777
-
SSH/GPG files MUST be:
- Private keys: 600 (rw-------)
- Public keys: 644 (rw-r--r--)
- ~/.ssh directory: 700 (rwx------)
Directories (MEDIUM priority):
- Standard directories: 755 (rwxr-xr-x)
- Private directories: 750 or 700
- Never 777 (world-writable)
Workflow
-
Parse arguments
Extract path, strict, check-executables, report-all Validate path exists Determine scan scope -
Execute permission checker
Execute .scripts/permission-checker.sh "$path" "$strict" "$check_executables" "$report_all" Returns: - 0: All permissions correct - 1: Permission issues found - 2: Scan error -
Analyze results
Categorize findings: - CRITICAL: 777, 666, world-writable - HIGH: Executables without shebangs, 775 on sensitive files - MEDIUM: Overly permissive configs, wrong directory perms - LOW: Inconsistent permissions, non-executable scripts Generate fix commands -
Format output
File Permission Audit Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Path: <path> Files Checked: <count> CRITICAL Issues (<count>): ❌ scripts/deploy.sh (777) Current: rwxrwxrwx (777) Issue: World-writable and executable Risk: Anyone can modify and execute script Fix: chmod 755 scripts/deploy.sh ❌ config/secrets.json (666) Current: rw-rw-rw- (666) Issue: World-writable configuration Risk: Secrets can be modified by anyone Fix: chmod 600 config/secrets.json HIGH Issues (<count>): ⚠️ bin/cli.sh (755) - Missing shebang Issue: Executable without shebang Fix: Add #!/usr/bin/env bash to first line MEDIUM Issues (<count>): 💡 .env (644) Current: rw-r--r-- (644) Recommendation: Restrict to owner only Fix: chmod 600 .env Summary: - Total issues: <count> - Critical: <count> (fix immediately) - Fixes available: Yes
Permission Patterns
Standard File Permissions:
644 (rw-r--r--) - Regular files, documentation
755 (rwxr-xr-x) - Executable scripts, directories
600 (rw-------) - Sensitive configs, private keys
700 (rwx------) - Private directories (.ssh, .gnupg)
Forbidden Permissions:
777 (rwxrwxrwx) - Never use (world-writable + executable)
666 (rw-rw-rw-) - Never use (world-writable)
000 (---------) - Inaccessible (likely error)
Context-Specific:
Shell scripts: 755 with #!/bin/bash
Python scripts: 755 with #!/usr/bin/env python3 (if CLI)
644 without shebang (if library)
Config files: 600 (sensitive) or 644 (public)
SSH keys: 600 (private), 644 (public)
Directories: 755 (public), 700 (private)
Shebang Validation
Valid shebangs:
#!/bin/bash
#!/usr/bin/env bash
#!/usr/bin/env python3
#!/usr/bin/env node
#!/usr/bin/env ruby
Invalid patterns:
#!/bin/sh # Too generic, prefer bash
#! /bin/bash # Space after #!
# /usr/bin/env bash # Missing !
Examples
# Check all permissions in current directory
/security-scan permissions path:.
# Strict mode - flag all non-standard permissions
/security-scan permissions path:. strict:true
# Check executables for shebangs
/security-scan permissions path:./scripts/ check-executables:true
# Report all files, not just issues
/security-scan permissions path:. report-all:true
Error Handling
Path not found:
ERROR: Path does not exist: <path>
Remediation: Verify path and try again
Permission denied:
ERROR: Cannot read permissions for: <path>
Remediation: Run with sufficient privileges or check ownership
No issues found:
SUCCESS: All file permissions correct
No action required
Automated Fixes
Critical Issues:
# Fix world-writable files
find . -type f -perm 0666 -exec chmod 644 {} \;
find . -type f -perm 0777 -exec chmod 755 {} \;
# Fix world-writable directories
find . -type d -perm 0777 -exec chmod 755 {} \;
Sensitive Files:
# Restrict sensitive configs
chmod 600 .env
chmod 600 config/credentials.json
chmod 600 ~/.ssh/id_rsa
# Secure directories
chmod 700 ~/.ssh
chmod 700 ~/.gnupg
Executables:
# Make scripts executable
chmod +x scripts/*.sh
# Remove execute from libraries
chmod 644 src/**/*.py
Platform-Specific Notes
Unix/Linux:
- Full permission support (owner/group/other)
- Numeric (755) or symbolic (rwxr-xr-x) modes
- Respect umask settings
macOS:
- Same as Unix/Linux
- Additional extended attributes (xattr)
- May have quarantine attributes on downloaded files
Windows (WSL/Git Bash):
- Limited permission support
- Executable bit preserved in git
- May show 755 for all files by default
Strict Mode Rules
When strict:true:
Additional checks:
- Flag 775 on any file (group-writable)
- Flag 755 on non-executable files
- Require 600 for all .env files
- Require 700 for all .ssh, .gnupg directories
- Flag inconsistent permissions in same directory
Stricter recommendations:
- Config files: Must be 600
- Scripts: Must have correct shebang
- No group-writable files
- Directories: 750 instead of 755
Remediation Guidance
For world-writable files (777, 666):
- Determine correct permission level
- Apply fix immediately:
chmod 644 <file>orchmod 755 <executable> - Verify no unauthorized modifications
- Check git history for permission changes
- Document required permissions in README
For executables without shebangs:
- Add appropriate shebang:
#!/usr/bin/env bash - Verify script runs correctly
- Consider using absolute path if specific version needed
For overly permissive configs:
- Restrict to owner:
chmod 600 <config> - Verify application can still read
- Update deployment documentation
- Use principle of least privilege
For inconsistent permissions:
- Establish permission standards
- Document in CONTRIBUTING.md
- Add pre-commit hook to enforce
- Use tools like .editorconfig
Security Best Practices
General:
- Use most restrictive permissions possible
- Never use 777 or 666
- Sensitive files: 600 (owner read/write only)
- Executables: 755 (everyone execute, owner write)
- Configs: 644 (everyone read, owner write) or 600 (owner only)
For Scripts:
- Always include shebang
- Make executable only if meant to be run directly
- Libraries should be 644, not 755
- Verify no secrets in scripts
For Keys:
- Private keys: 600 or SSH refuses to use them
- Public keys: 644
- Key directories: 700
- Never group or world readable
Output Format
{
"scan_type": "permissions",
"path": "<path>",
"files_checked": <count>,
"issues_found": <count>,
"severity_breakdown": {
"critical": <count>,
"high": <count>,
"medium": <count>,
"low": <count>
},
"findings": [
{
"file": "<file_path>",
"current_permissions": "<octal>",
"current_symbolic": "<symbolic>",
"issue": "<issue_description>",
"severity": "<severity>",
"risk": "<risk_description>",
"recommended_permissions": "<octal>",
"fix_command": "chmod <perms> <file>"
}
],
"fixes_available": <boolean>,
"action_required": <boolean>
}
Request: $ARGUMENTS
Operation: Check URL Safety
Validate URL safety, enforce HTTPS, and detect malicious patterns in URLs and code.
Parameters from $ARGUMENTS
- path: Target directory or file to scan (required)
- https-only: Enforce HTTPS for all URLs (true|false, default: false)
- allow-localhost: Allow http://localhost URLs (true|false, default: true)
- check-code-patterns: Check for dangerous code execution patterns (true|false, default: true)
URL Safety Checks
Protocol Validation:
- HTTPS enforcement (production contexts)
- HTTP allowed only for localhost/127.0.0.1
- FTP/telnet flagged as insecure
- file:// protocol flagged (potential security risk)
Malicious Patterns:
curl ... | sh- Remote code executionwget ... | bash- Remote script executioneval(fetch(...))- Dynamic code executionexec(...)with URLs - Command injection riskrm -rfin scripts downloaded from URLs- Obfuscated URLs (base64, hex encoded)
Domain Validation:
- Check for typosquatting (common package registries)
- Suspicious TLDs (.tk, .ml, .ga, .cf)
- IP addresses instead of domains
- Shortened URLs (bit.ly, tinyurl) - potential phishing
Workflow
-
Parse arguments
Extract path, https-only, allow-localhost, check-code-patterns Validate path exists Determine scan scope -
Execute URL validator
Execute .scripts/url-validator.py "$path" "$https_only" "$allow_localhost" "$check_code_patterns" Returns: - 0: All URLs safe - 1: Unsafe URLs detected - 2: Validation error -
Analyze results
Categorize findings: - CRITICAL: Remote code execution patterns - HIGH: Non-HTTPS in production, obfuscated URLs - MEDIUM: HTTP in non-localhost, suspicious TLDs - LOW: Shortened URLs, IP addresses Generate context-aware remediation -
Format output
URL Safety Scan Results ━━━━━━━━━━━━━━━━━━━━━━ Path: <path> URLs Scanned: <count> CRITICAL Issues (<count>): ❌ <file>:<line>: Remote code execution pattern Pattern: curl https://example.com/script.sh | bash Risk: Executes arbitrary code without verification Remediation: Download, verify, then execute HIGH Issues (<count>): ⚠️ <file>:<line>: Non-HTTPS URL in production context URL: http://api.example.com Risk: Man-in-the-middle attacks Remediation: Use HTTPS Summary: - Total URLs: <count> - Safe: <count> - Unsafe: <count> - Action required: <yes|no>
Dangerous Code Patterns
Remote Execution (CRITICAL):
# Dangerous patterns
curl https://example.com/install.sh | bash
wget -qO- https://get.example.com | sh
eval "$(curl -fsSL https://example.com/script)"
bash <(curl -s https://example.com/setup.sh)
Dynamic Code Execution (HIGH):
// Dangerous patterns
eval(fetch(url).then(r => r.text()))
new Function(await fetch(url).text())()
exec(`curl ${url}`)
Command Injection (HIGH):
# Vulnerable patterns
wget $USER_INPUT
curl "$UNTRUSTED_URL"
git clone $URL # without validation
Safe Alternatives
Instead of curl | sh:
# Safe: Download, verify, then execute
wget https://example.com/install.sh
sha256sum -c install.sh.sha256
chmod +x install.sh
./install.sh
Instead of eval(fetch()):
// Safe: Fetch as data, validate, then use
const response = await fetch(url);
const data = await response.json();
// Process data, not as code
Examples
# Check all URLs, enforce HTTPS
/security-scan urls path:. https-only:true
# Allow localhost HTTP during development
/security-scan urls path:. https-only:true allow-localhost:true
# Check for code execution patterns
/security-scan urls path:./scripts/ check-code-patterns:true
# Scan specific file
/security-scan urls path:./install.sh
Error Handling
Path not found:
ERROR: Path does not exist: <path>
Remediation: Verify path and try again
No URLs found:
INFO: No URLs detected
No action required
Python unavailable:
ERROR: Python3 not available
Remediation: Install Python 3.x or skip URL validation
Context-Aware Rules
Production contexts (strict):
- package.json scripts
- Dockerfiles
- CI/CD configs (.github/, .gitlab-ci.yml)
- Installation scripts (install.sh, setup.sh) → Enforce HTTPS, no remote execution
Development contexts (relaxed):
- Test files (test, spec)
- Mock data
- Local development configs → Allow HTTP for localhost
Documentation contexts (informational):
- README.md
- *.md files
- Comments → Flag but don't fail
URL Categories
Registry URLs (validate carefully):
- npm: https://registry.npmjs.org
- PyPI: https://pypi.org
- Docker: https://registry.hub.docker.com
- GitHub: https://github.com → Verify exact domain, check for typosquatting
CDN URLs (HTTPS required):
- https://cdn.jsdelivr.net
- https://unpkg.com
- https://cdnjs.cloudflare.com → Must use HTTPS, verify integrity hashes
Shortened URLs (flag for review):
- bit.ly, tinyurl.com, goo.gl → Cannot verify destination, recommend expanding
Remediation Guidance
For remote code execution:
- Remove pipe-to-shell patterns
- Download scripts explicitly
- Verify checksums/signatures
- Review code before execution
- Use official package managers when possible
For non-HTTPS URLs:
- Update to HTTPS version
- Verify certificate validity
- Pin certificate if highly sensitive
- Consider using subresource integrity (SRI) for CDNs
For suspicious URLs:
- Verify domain legitimacy
- Check for typosquatting
- Expand shortened URLs
- Review destination manually
Output Format
{
"scan_type": "urls",
"path": "<path>",
"urls_scanned": <count>,
"unsafe_urls": <count>,
"severity_breakdown": {
"critical": <count>,
"high": <count>,
"medium": <count>,
"low": <count>
},
"findings": [
{
"file": "<file_path>",
"line": <line_number>,
"url": "<url>",
"issue": "<issue_type>",
"severity": "<severity>",
"risk": "<risk_description>",
"remediation": "<action>"
}
],
"action_required": <boolean>
}
Request: $ARGUMENTS
Operation: Full Security Audit
Execute comprehensive security audit combining all security scans: secrets, URLs, files, and permissions.
Parameters from $ARGUMENTS
- path: Target directory to audit (required)
- severity: Minimum severity to report (critical|high|medium|low, default: medium)
- strict: Enable strict mode for all checks (true|false, default: false)
- format: Output format (text|json|markdown, default: text)
Full Audit Workflow
-
Initialize audit
Validate path exists Parse severity threshold Set strict mode for all sub-scans Initialize results aggregator -
Execute all security scans
PARALLEL EXECUTION (where possible): ┌─ Scan 1: Secret Detection │ Read scan-secrets.md │ Execute with path, recursive:true, severity │ Capture results │ ├─ Scan 2: URL Safety Check │ Read check-urls.md │ Execute with path, https-only, check-code-patterns │ Capture results │ ├─ Scan 3: Dangerous Files │ Read scan-files.md │ Execute with path, include-hidden, check-gitignore │ Capture results │ └─ Scan 4: Permission Audit Read check-permissions.md Execute with path, strict, check-executables Capture results -
Aggregate results
Combine all findings Deduplicate issues Sort by severity: 1. CRITICAL issues (block publication) 2. HIGH issues (fix before publication) 3. MEDIUM issues (recommended fixes) 4. LOW issues (nice to have) Calculate overall security score: Base score: 100 - CRITICAL: -25 points each - HIGH: -10 points each - MEDIUM: -5 points each - LOW: -2 points each Score = max(0, base - deductions) -
Generate comprehensive report
FULL SECURITY AUDIT REPORT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Target: <path> Scan Date: <timestamp> Severity Threshold: <severity> OVERALL SECURITY SCORE: <0-100>/100 Rating: <Excellent|Good|Fair|Poor|Critical> Publication Ready: <Yes|No|With Fixes> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ EXECUTIVE SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Security Posture: <assessment> Critical Issues: <count> (IMMEDIATE ACTION REQUIRED) High Priority: <count> (FIX BEFORE PUBLICATION) Medium Priority: <count> (RECOMMENDED) Low Priority: <count> (OPTIONAL) Action Required: <Yes|No> Estimated Fix Time: <time_estimate> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SCAN RESULTS BY LAYER ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [1] SECRET DETECTION Status: <PASS|FAIL> Secrets Found: <count> Files Scanned: <count> <Details...> [2] URL SAFETY Status: <PASS|FAIL> Unsafe URLs: <count> URLs Checked: <count> <Details...> [3] DANGEROUS FILES Status: <PASS|FAIL> Dangerous Files: <count> Files Scanned: <count> <Details...> [4] FILE PERMISSIONS Status: <PASS|FAIL> Permission Issues: <count> Files Checked: <count> <Details...> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ CRITICAL ISSUES (IMMEDIATE ACTION) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ❌ Issue 1: <description> File: <path>:<line> Severity: CRITICAL Risk: <risk_assessment> Remediation: <specific_steps> ❌ Issue 2: ... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ HIGH PRIORITY ISSUES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ Issue 1: ... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ REMEDIATION PLAN ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Phase 1: Critical Issues (Immediate) □ Remove exposed secrets from .env □ Rotate compromised API keys □ Fix world-writable permissions (777) □ Remove dangerous files from repository Phase 2: High Priority (Before Publication) □ Update all HTTP URLs to HTTPS □ Add dangerous files to .gitignore □ Fix executables without shebangs □ Remove remote code execution patterns Phase 3: Recommended Improvements □ Restrict config file permissions to 600 □ Review and expand shortened URLs □ Add security documentation Phase 4: Optional Enhancements □ Implement pre-commit hooks □ Add automated security scanning to CI/CD □ Document security best practices ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SECURITY RECOMMENDATIONS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔒 Secrets Management - Use environment variables for all secrets - Implement secret rotation policy - Consider using secret management tools (AWS Secrets Manager, HashiCorp Vault) 🌐 URL Security - Enforce HTTPS for all external URLs - Verify checksums for downloaded scripts - Never pipe remote content to shell 📁 File Security - Review .gitignore completeness - Remove sensitive files from git history - Implement file scanning in CI/CD 🔐 Permission Security - Use least privilege principle - Document required permissions - Regular permission audits ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PUBLICATION READINESS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ <if score >= 90> ✅ READY FOR PUBLICATION Security score is excellent. No critical issues found. All security checks passed. Safe to publish. <if 70 <= score < 90> ⚠️ READY WITH MINOR FIXES Security score is good but has some issues. Fix high priority issues before publication. Estimated fix time: <time> <if score < 70> ❌ NOT READY FOR PUBLICATION Critical security issues must be resolved. Publication blocked until critical issues fixed. Do not publish in current state. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ NEXT STEPS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. Address all CRITICAL issues immediately 2. Fix HIGH priority issues before publication 3. Review and implement recommended improvements 4. Re-run full security audit to verify fixes 5. Document security practices for maintainers
Security Score Calculation
Base Score: 100 points
Deductions:
- CRITICAL issues: -25 points each
- HIGH issues: -10 points each
- MEDIUM issues: -5 points each
- LOW issues: -2 points each
Final Score: max(0, Base - Deductions)
Rating Scale:
- 90-100: Excellent ⭐⭐⭐⭐⭐ (Publication ready)
- 70-89: Good ⭐⭐⭐⭐ (Ready with minor fixes)
- 50-69: Fair ⭐⭐⭐ (Needs work)
- 30-49: Poor ⭐⭐ (Not ready)
- 0-29: Critical ⭐ (Major security issues)
Examples
# Full security audit with default settings
/security-scan full-security-audit path:.
# Strict mode - enforce all strict rules
/security-scan full-security-audit path:. strict:true
# Only report critical and high issues
/security-scan full-security-audit path:. severity:high
# JSON output for CI/CD integration
/security-scan full-security-audit path:. format:json
# Markdown report for documentation
/security-scan full-security-audit path:. format:markdown
Error Handling
Path not found:
ERROR: Path does not exist: <path>
Remediation: Verify path and try again
Scan failures:
WARNING: One or more security scans failed
Partial results available:
- Secrets: ✓ Completed
- URLs: ✓ Completed
- Files: ✗ Failed
- Permissions: ✓ Completed
Recommendation: Review failures and re-run
All scans passed:
SUCCESS: Full Security Audit Passed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Security Score: 100/100 ⭐⭐⭐⭐⭐
Rating: Excellent
All security checks passed with no issues.
Your plugin/marketplace is secure and ready for publication.
Summary:
✓ No secrets detected
✓ All URLs safe
✓ No dangerous files
✓ All permissions correct
Excellent security posture! 🎉
Integration with CI/CD
GitHub Actions Example:
name: Security Audit
on: [push, pull_request]
jobs:
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Security Audit
run: |
/security-scan full-security-audit path:. format:json > security-report.json
- name: Check Security Score
run: |
score=$(jq '.security_score' security-report.json)
if [ $score -lt 70 ]; then
echo "Security score too low: $score"
exit 1
fi
- name: Upload Report
uses: actions/upload-artifact@v3
with:
name: security-report
path: security-report.json
GitLab CI Example:
security_audit:
stage: test
script:
- /security-scan full-security-audit path:. format:json
only:
- main
- merge_requests
artifacts:
reports:
security: security-report.json
Report Formats
Text Format (default):
- Human-readable console output
- Color-coded severity levels
- Section dividers for clarity
- Suitable for terminal viewing
JSON Format:
{
"scan_type": "full-audit",
"timestamp": "<ISO8601>",
"path": "<path>",
"security_score": <0-100>,
"rating": "<rating>",
"publication_ready": <boolean>,
"scans": {
"secrets": { "status": "pass", "issues": [] },
"urls": { "status": "fail", "issues": [...] },
"files": { "status": "pass", "issues": [] },
"permissions": { "status": "pass", "issues": [] }
},
"severity_breakdown": {
"critical": <count>,
"high": <count>,
"medium": <count>,
"low": <count>
},
"all_findings": [...],
"remediation_plan": [...],
"recommendations": [...]
}
Markdown Format:
- GitHub/GitLab compatible
- Can be added to PR comments
- Suitable for documentation
- Includes tables and checkboxes
Time Estimates
By Issue Count:
- 0 issues: No time needed ✅
- 1-3 CRITICAL: 2-4 hours
- 4-10 HIGH: 1-2 hours
- 11-20 MEDIUM: 30-60 minutes
- 20+ LOW: 15-30 minutes
By Issue Type:
- Secret rotation: 30-60 minutes each
- URL updates: 5-10 minutes each
- File removal: 15-30 minutes (including .gitignore)
- Permission fixes: 5 minutes total (batch operation)
Remediation Verification
After fixing issues, re-run audit:
# Fix issues
chmod 755 scripts/*.sh
git rm .env
echo ".env" >> .gitignore
# Verify fixes
/security-scan full-security-audit path:.
# Should see improved score
Best Practices
Regular Audits:
- Run before each release
- Include in CI/CD pipeline
- Weekly scans for active development
- After adding dependencies
Fix Priority:
- CRITICAL: Drop everything and fix
- HIGH: Fix within 24 hours
- MEDIUM: Fix within 1 week
- LOW: Address when convenient
Team Communication:
- Share audit results with team
- Document security requirements
- Train on secure development
- Review security in code reviews
Output Format
{
"scan_type": "full-audit",
"timestamp": "<ISO8601>",
"path": "<path>",
"security_score": <0-100>,
"rating": "<Excellent|Good|Fair|Poor|Critical>",
"publication_ready": <boolean>,
"estimated_fix_time": "<time_string>",
"severity_breakdown": {
"critical": <count>,
"high": <count>,
"medium": <count>,
"low": <count>
},
"scan_results": {
"secrets": { "status": "pass|fail", "findings": [...] },
"urls": { "status": "pass|fail", "findings": [...] },
"files": { "status": "pass|fail", "findings": [...] },
"permissions": { "status": "pass|fail", "findings": [...] }
},
"all_findings": [...],
"remediation_plan": [...],
"recommendations": [...],
"action_required": <boolean>
}
Request: $ARGUMENTS
Operation: Scan for Dangerous Files
Detect dangerous files, sensitive configurations, and files that should not be committed to version control.
Parameters from $ARGUMENTS
- path: Target directory to scan (required)
- patterns: Specific file patterns to check (optional, default: all)
- include-hidden: Scan hidden files and directories (true|false, default: true)
- check-gitignore: Verify .gitignore coverage (true|false, default: true)
Dangerous File Categories
Environment Files (CRITICAL):
- .env, .env.local, .env.production, .env.development
- .env.*.local (any environment-specific)
- env.sh, setenv.sh → Often contain secrets, should never be committed
Credential Files (CRITICAL):
- credentials.json, credentials.yaml, credentials.yml
- secrets.json, secrets.yaml, config/secrets/*
- .aws/credentials, .azure/credentials
- .gcp/credentials.json, gcloud/credentials → Direct access credentials, rotate if exposed
Private Keys (CRITICAL):
- id_rsa, id_dsa, id_ed25519 (SSH keys)
- *.pem, *.key, *.p12, *.pfx (SSL/TLS certificates)
- *.jks, *.keystore (Java keystores)
- .gnupg/, .ssh/id_ (GPG and SSH directories) → Authentication keys, regenerate if exposed
Database Files (HIGH):
- *.db, *.sqlite, *.sqlite3
- *.sql with INSERT statements (data dumps)
- dump.sql, backup.sql
- *.mdb, *.accdb (Access databases) → May contain sensitive data
Configuration Files (MEDIUM):
- config/database.yml with passwords
- appsettings.json with connection strings
- wp-config.php with DB credentials
- settings.py with SECRET_KEY → Review for hardcoded secrets
Backup Files (MEDIUM):
- *.bak, *.backup, *.old
- *~, *.swp, *.swo (editor backups)
- *.orig, *.copy → May contain previous versions with secrets
Log Files (LOW):
- *.log with potential sensitive data
- debug.log, error.log
- Combined log files (>10MB) → Review for leaked information
Workflow
-
Parse arguments
Extract path, patterns, include-hidden, check-gitignore Validate path exists and is directory Load dangerous file patterns -
Execute file scanner
Execute .scripts/file-scanner.sh "$path" "$patterns" "$include_hidden" "$check_gitignore" Returns: - 0: No dangerous files found - 1: Dangerous files detected - 2: Scan error -
Process results
Categorize by risk: - CRITICAL: Private keys, credentials, production env files - HIGH: Database files, config with secrets - MEDIUM: Backup files, test credentials - LOW: Log files, temporary files Cross-reference with .gitignore: - Files that SHOULD be in .gitignore but aren't - Already ignored files (informational) -
Format output
Dangerous Files Scan Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Path: <path> Files Scanned: <count> CRITICAL Files (<count>): ❌ .env (157 bytes) Type: Environment file Risk: Contains API keys and secrets Status: NOT in .gitignore ⚠️ Remediation: Add to .gitignore, remove from git history ❌ config/credentials.json (2.3 KB) Type: Credential file Risk: Contains authentication credentials Status: NOT in .gitignore ⚠️ Remediation: Remove, rotate credentials, use env vars HIGH Files (<count>): ⚠️ database/dev.db (45 MB) Type: SQLite database Risk: May contain user data Status: In .gitignore ✓ Remediation: Verify .gitignore working Summary: - Total dangerous files: <count> - Not in .gitignore: <count> - Action required: <yes|no>
File Pattern Signatures
Environment files:
.env
.env.*
env.sh
setenv.sh
.envrc
Credential files:
*credentials*
*secrets*
*password*
.aws/credentials
.azure/credentials
.gcp/*credentials*
Private keys:
id_rsa
id_dsa
id_ed25519
*.pem
*.key
*.p12
*.pfx
*.jks
*.keystore
.gnupg/*
Database files:
*.db
*.sqlite
*.sqlite3
*.sql (with INSERT/UPDATE)
dump.sql
*backup*.sql
Backup patterns:
*.bak
*.backup
*.old
*.orig
*.copy
*~
*.swp
*.swo
.gitignore Validation
Should be ignored:
# Environment
.env*
!.env.example
# Credentials
credentials.*
secrets.*
*.pem
*.key
id_rsa*
# Databases
*.db
*.sqlite*
dump.sql
# Backups
*.bak
*.backup
*~
Safe to commit (examples):
.env.example
.env.template
credentials.example.json
README.md
package.json
Examples
# Scan current directory
/security-scan files path:.
# Check specific patterns only
/security-scan files path:. patterns:".env,credentials,*.pem"
# Include hidden files explicitly
/security-scan files path:. include-hidden:true
# Scan and verify .gitignore coverage
/security-scan files path:. check-gitignore:true
Error Handling
Path not found:
ERROR: Path does not exist: <path>
Remediation: Verify path is correct
Path is not directory:
ERROR: Path is not a directory: <path>
Remediation: Provide directory path for file scanning
No .gitignore found:
WARNING: No .gitignore file found
Recommendation: Create .gitignore to prevent committing sensitive files
Remediation Guidance
For environment files (.env):
- Add to .gitignore immediately
- Remove from git history if committed:
git filter-branch --force --index-filter \ "git rm --cached --ignore-unmatch .env" \ --prune-empty --tag-name-filter cat -- --all - Create .env.example with dummy values
- Document environment variables in README
For credential files:
- Remove from repository
- Rotate all exposed credentials
- Use environment variables or secret managers
- Add to .gitignore
- Consider using git-secrets or similar tools
For private keys:
- Regenerate keys immediately
- Remove from repository
- Update deployed systems with new keys
- Add *.pem, *.key, id_rsa to .gitignore
- Audit access logs for unauthorized use
For database files:
- Remove from repository if contains real data
- For test data, ensure no real emails/names
- Add *.db, *.sqlite to .gitignore
- Use schema-only dumps in version control
For backup files:
- Clean up backup files before commit
- Add backup patterns to .gitignore
- Use .gitignore_global for editor backups
- Configure editors to save backups elsewhere
Git History Cleanup
If sensitive files were already committed:
# Using git filter-repo (recommended)
git filter-repo --path .env --invert-paths
# Using BFG Repo-Cleaner (fast for large repos)
bfg --delete-files .env
git reflog expire --expire=now --all
git gc --prune=now --aggressive
# Force push (WARNING: destructive)
git push origin --force --all
Prevention Strategies
Pre-commit hooks:
# .git/hooks/pre-commit
#!/bin/bash
# Check for dangerous files
if git diff --cached --name-only | grep -E '\\.env$|credentials|id_rsa'; then
echo "ERROR: Attempting to commit sensitive file"
exit 1
fi
Use git-secrets:
git secrets --install
git secrets --register-aws
git secrets --add 'credentials\.json'
IDE Configuration:
- Configure .gitignore templates
- Use .editorconfig
- Set up file watchers for dangerous patterns
Output Format
{
"scan_type": "files",
"path": "<path>",
"files_scanned": <count>,
"dangerous_files": <count>,
"not_in_gitignore": <count>,
"severity_breakdown": {
"critical": <count>,
"high": <count>,
"medium": <count>,
"low": <count>
},
"findings": [
{
"file": "<file_path>",
"type": "<file_type>",
"size": <size_bytes>,
"severity": "<severity>",
"risk": "<risk_description>",
"in_gitignore": <boolean>,
"remediation": "<action>"
}
],
"action_required": <boolean>
}
Request: $ARGUMENTS
Operation: Scan for Exposed Secrets
Detect exposed secrets, API keys, tokens, passwords, and private keys using 50+ pattern signatures.
Parameters from $ARGUMENTS
- path: Target directory or file to scan (required)
- recursive: Scan subdirectories (true|false, default: true)
- patterns: Specific pattern categories to check (optional, default: all)
- exclude: Patterns to exclude from scan (optional)
- severity: Minimum severity to report (critical|high|medium|low, default: medium)
Secret Detection Patterns (50+)
API Keys & Tokens:
- Stripe: sk_live_, sk_test_, pk_live_, pk_test_
- OpenAI: sk-[a-zA-Z0-9]{32,}
- AWS: AKIA[0-9A-Z]{16}
- Google: AIza[0-9A-Za-z_-]{35}
- GitHub: ghp_, gho_, ghs_, ghu_
- Slack: xox[baprs]-[0-9a-zA-Z]{10,}
- Twitter: [0-9a-zA-Z]{35,44}
- Facebook: EAA[0-9A-Za-z]{90,}
Private Keys:
- RSA: BEGIN RSA PRIVATE KEY
- Generic: BEGIN PRIVATE KEY
- SSH: BEGIN OPENSSH PRIVATE KEY
- PGP: BEGIN PGP PRIVATE KEY
- DSA: BEGIN DSA PRIVATE KEY
- EC: BEGIN EC PRIVATE KEY
Credentials:
- Passwords: password\s*[=:]\s*['"][^'"]+['"]
- API keys: api[_-]?key\s*[=:]\s*['"][^'"]+['"]
- Secrets: secret\s*[=:]\s*['"][^'"]+['"]
- Tokens: token\s*[=:]\s*['"][^'"]+['"]
- Auth: authorization\s*[=:]\s*['"]Bearer [^'"]+['"]
Cloud Provider Credentials:
- AWS Access Key: aws_access_key_id
- AWS Secret: aws_secret_access_key
- Azure: [0-9a-zA-Z/+]{88}==
- GCP Service Account: type.*service_account
Workflow
-
Parse arguments
Extract path, recursive, patterns, exclude, severity Validate path exists Determine scan scope (file vs directory) -
Execute secret scanner
Execute .scripts/secret-scanner.sh "$path" "$recursive" "$patterns" "$exclude" "$severity" Returns: - 0: No secrets found - 1: Secrets detected - 2: Scan error -
Process results
Parse scanner output Categorize by severity: - CRITICAL: Private keys, production API keys - HIGH: API keys, tokens with broad scope - MEDIUM: Passwords, secrets in config - LOW: Test keys, development credentials Generate remediation guidance per finding -
Format output
Secrets Scan Results ━━━━━━━━━━━━━━━━━━━━ Path: <path> Files Scanned: <count> CRITICAL Issues (<count>): ❌ <file>:<line>: <type> detected Pattern: <pattern_name> Remediation: Remove and rotate immediately HIGH Issues (<count>): ⚠️ <file>:<line>: <type> detected Summary: - Total secrets: <count> - Unique patterns: <count> - Action required: <yes|no>
Examples
# Scan current directory recursively
/security-scan secrets path:.
# Scan specific file only
/security-scan secrets path:./config/settings.json recursive:false
# Check only API key patterns
/security-scan secrets path:. patterns:"api-keys,tokens"
# Exclude test directories
/security-scan secrets path:. exclude:"test,mock,fixtures"
# Only critical severity
/security-scan secrets path:. severity:critical
Error Handling
Path not found:
ERROR: Path does not exist: <path>
Remediation: Verify path and try again
No patterns matched:
INFO: No secrets detected
All files clean
Scanner unavailable:
ERROR: Secret scanner script not found
Remediation: Verify plugin installation
Severity Levels
CRITICAL (Immediate action required):
- Private keys (RSA, SSH, PGP)
- Production API keys (live_, prod_)
- AWS credentials
- Database connection strings with passwords
HIGH (Action required):
- API keys (generic)
- OAuth tokens
- Bearer tokens
- Authentication credentials
MEDIUM (Should address):
- Passwords in config files
- Secret variables
- Session tokens
- Development credentials in non-test contexts
LOW (Review recommended):
- Test API keys
- Mock credentials
- Example configurations
Remediation Guidance
For exposed secrets:
- Remove from code immediately
- Rotate/regenerate the credential
- Use environment variables instead
- Add to .gitignore if file-based
- Review git history for exposure
- Consider using secret management (AWS Secrets Manager, HashiCorp Vault)
Prevention:
- Use .env files (never commit)
- Use environment variables
- Implement pre-commit hooks
- Use secret scanning in CI/CD
- Educate team on security practices
Output Format
{
"scan_type": "secrets",
"path": "<path>",
"files_scanned": <count>,
"secrets_found": <count>,
"severity_breakdown": {
"critical": <count>,
"high": <count>,
"medium": <count>,
"low": <count>
},
"findings": [
{
"file": "<file_path>",
"line": <line_number>,
"type": "<secret_type>",
"severity": "<severity>",
"pattern": "<pattern_name>",
"remediation": "<action>"
}
],
"action_required": <boolean>
}
Request: $ARGUMENTS
You are the Security Scan coordinator, protecting against security vulnerabilities and exposed secrets.
Your Mission
Parse $ARGUMENTS to determine the requested security scan operation and route to the appropriate sub-command.
Available Operations
Parse the first word of $ARGUMENTS to determine which operation to execute:
- secrets → Read
.claude/commands/security-scan/scan-secrets.md - urls → Read
.claude/commands/security-scan/check-urls.md - files → Read
.claude/commands/security-scan/scan-files.md - permissions → Read
.claude/commands/security-scan/check-permissions.md - full-security-audit → Read
.claude/commands/security-scan/full-audit.md
Argument Format
/security-scan <operation> [parameters]
Examples
# Scan for exposed secrets
/security-scan secrets path:. recursive:true
# Validate URL safety
/security-scan urls path:. https-only:true
# Detect dangerous files
/security-scan files path:. patterns:".env,credentials.json,id_rsa"
# Check file permissions
/security-scan permissions path:. strict:true
# Run complete security audit
/security-scan full-security-audit path:.
Security Checks
Secret Detection (50+ patterns):
- API keys: sk-, pk-, token-
- AWS credentials: AKIA, aws_access_key_id
- Private keys: BEGIN PRIVATE KEY, BEGIN RSA PRIVATE KEY
- Passwords: password=, pwd=
- Tokens: Bearer, Authorization
URL Safety:
- HTTPS enforcement
- Malicious pattern detection: eval(), exec(), rm -rf
- Curl/wget piping: curl | sh, wget | bash
Dangerous Files:
- .env files with secrets
- credentials.json, config.json with keys
- Private keys: id_rsa, *.pem, *.key
- Database dumps with data
File Permissions:
- No world-writable files (777)
- Scripts executable only when needed
- Config files read-only (644)
Error Handling
If the operation is not recognized:
- List all available security operations
- Show security best practices
- Provide remediation guidance
Base Directory
Base directory for this skill: .claude/commands/security-scan/
Your Task
- Parse
$ARGUMENTSto extract operation and parameters - Read the corresponding operation file
- Execute security scans with pattern matching
- Return prioritized security findings with remediation steps
Current Request: $ARGUMENTS
Validate Marketplace
You are a marketplace validation specialist. Your task is to comprehensively validate a Claude Code marketplace.json file.
Process
1. Locate Marketplace File
Determine the marketplace.json path:
- If user provided an argument ($1): Use that path
- If no argument: Look for
.claude-plugin/marketplace.jsonin current directory - Auto-detect: Search up directory tree for
.claude-plugin/marketplace.json
2. Run Validation Script
Execute the validation script located at:
${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace-full.sh [path]
The script will validate:
- JSON syntax
- Required fields (name, owner, plugins)
- Optional recommended fields
- Plugin entries structure
- Quality scoring
- Security checks
3. Interpret Results
The script outputs:
- ✅ Success messages for valid items
- ❌ Errors for critical issues
- ⚠️ Warnings for recommended improvements
- ℹ️ Info for suggestions
Quality Score:
- 90-100: Excellent ⭐⭐⭐⭐⭐
- 75-89: Good ⭐⭐⭐⭐
- 60-74: Fair ⭐⭐⭐
- 40-59: Needs Improvement ⭐⭐
- 0-39: Poor ⭐
4. Provide Recommendations
Based on validation results, provide:
- Critical Issues: Must be fixed before publication
- Warnings: Should be addressed for quality
- Suggestions: Would improve discoverability and usability
5. Summary
Conclude with:
- Overall quality assessment
- Priority action items
- Publication readiness status
Example Output Structure
🔍 Validating Marketplace: open-plugins
✅ JSON syntax valid
✅ Required fields present
✅ 3 plugins found
Plugin Validation:
✅ plugin-name (v1.0.0) - Excellent ⭐⭐⭐⭐⭐
⚠️ another-plugin (v0.1.0) - Fair ⭐⭐⭐
- Missing recommended field: keywords
- Description too short (< 50 chars)
Overall Quality Score: 85/100 - Good ⭐⭐⭐⭐
Recommendations:
1. Add keywords to another-plugin
2. Expand description in another-plugin
Summary: 1 excellent, 1 fair - Address warnings before publication
Error Handling
If validation fails:
- Show clear error messages
- Explain what's wrong
- Provide remediation steps
- Reference documentation if needed
Common issues:
- Invalid JSON: Show syntax error location
- Missing required fields: List which fields are missing
- Invalid formats: Show expected format
- Security issues: Explain the risk and how to fix
References
- Marketplace schema:
.claude/docs/plugins/plugin-marketplaces.md - Plugin standards:
.claude/docs/plugins/plugins-reference.md - OpenPlugins contributing:
open-plugins/CONTRIBUTING.md
Validate Plugin
You are a plugin validation specialist. Your task is to comprehensively validate a Claude Code plugin for quality, structure, and standards compliance.
Process
1. Locate Plugin Directory
Determine the plugin path:
- If user provided an argument ($1): Use that path
- If no argument: Use current directory
- Look for
plugin.jsonat plugin root to confirm it's a plugin
2. Run Validation Script
Execute the validation script located at:
${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-full.sh [path]
The script will validate:
- Structure: Directory layout, required files
- Metadata: plugin.json schema compliance
- Components: Commands, agents, hooks validation
- Quality: Documentation, completeness
- Security: No secrets, safe permissions
3. Interpret Results
The script outputs:
- ✅ Success messages for valid components
- ❌ Errors for critical issues (must fix)
- ⚠️ Warnings for recommended improvements
- ℹ️ Info for optional suggestions
Quality Score Categories:
- 90-100: Excellent ⭐⭐⭐⭐⭐ (publication-ready)
- 75-89: Good ⭐⭐⭐⭐ (minor improvements)
- 60-74: Fair ⭐⭐⭐ (needs work)
- 40-59: Needs Improvement ⭐⭐ (significant issues)
- 0-39: Poor ⭐ (not ready)
4. Provide Detailed Feedback
For each issue found, provide:
- What's wrong: Clear explanation
- Why it matters: Impact on functionality/quality
- How to fix: Specific remediation steps
- Examples: Show correct format
5. Prioritize Issues
Categorize findings:
- Critical: Prevents installation or functionality
- Important: Affects quality or user experience
- Recommended: Improves discoverability or maintenance
- Optional: Nice-to-have enhancements
6. Generate Action Plan
Create a numbered list of fixes in priority order:
- Fix critical errors first
- Address important warnings
- Implement recommended improvements
- Consider optional enhancements
Validation Checklist
Structure Validation
-
plugin.jsonexists at plugin root -
plugin.jsonin correct location - Component directories present (if used)
- README.md exists and complete
- LICENSE file present
Metadata Validation
- Required fields: name, version, description, author, license
- Name: lowercase-hyphen format
- Version: semantic versioning (X.Y.Z)
- Description: 50-200 characters
- Author: valid format (string or object)
- License: valid identifier
Component Validation
- Command files (*.md) have valid frontmatter
- Agent files have required fields (name, description)
- Hooks JSON is valid (if present)
- MCP configuration valid (if present)
- All referenced files exist
Quality Validation
- README has minimum sections
- No TODO or placeholder content
- Keywords present (3-7 recommended)
- CHANGELOG.md exists (recommended)
Security Validation
- No .env files with real credentials
- No API keys or tokens in code
- No suspicious file permissions
- HTTPS for external URLs
Example Output Structure
🔍 Validating Plugin: my-awesome-plugin
Structure:
✅ plugin.json exists at plugin root
✅ plugin.json schema valid
✅ Commands directory present (2 commands found)
⚠️ Agents directory missing (optional)
✅ README.md present and complete
❌ LICENSE file missing
Metadata:
✅ Name: my-awesome-plugin (valid format)
✅ Version: 1.0.0 (valid semver)
✅ Description: "A comprehensive plugin..." (132 chars)
❌ Author field missing
Components:
✅ commands/action.md - valid frontmatter
❌ commands/broken.md - missing description
Security:
✅ No exposed secrets
⚠️ File .env.example found (verify no real values)
Quality Score: 65/100 - Fair ⭐⭐⭐
Critical Issues (must fix):
1. Add LICENSE file (MIT recommended)
2. Add author field to plugin.json
3. Fix commands/broken.md frontmatter
Recommendations:
1. Add CHANGELOG.md for version tracking
2. Consider adding agents directory
3. Review .env.example for sensitive data
Status: NEEDS FIXES before publication
Error Handling
Provide helpful guidance for common issues:
Missing plugin.json:
Error: No plugin.json found at plugin root
This is required for all Claude Code plugins.
To fix:
1. Create plugin.json at plugin root directory
2. Add plugin.json with required fields
3. See: .claude/docs/plugins/plugins-reference.md
Invalid JSON:
Error: Invalid JSON syntax in plugin.json
Line 5: Expected comma or closing brace
To fix:
1. Validate JSON: cat plugin.json | python3 -m json.tool
2. Fix syntax errors
3. Ensure proper formatting
Missing Required Field:
Error: Missing required field: 'author'
The author field identifies the plugin creator.
To fix - Add to plugin.json:
"author": {
"name": "Your Name",
"email": "you@example.com"
}
Or use string format:
"author": "Your Name"
References
- Plugin schema:
.claude/docs/plugins/plugins-reference.md - OpenPlugins standards:
open-plugins/CONTRIBUTING.md - Best practices:
CLAUDE.mdin project
Quick Validate
You are a quick validation specialist. Your task is to rapidly validate a marketplace or plugin with essential checks only.
Process
1. Auto-Detect Target Type
Determine if the target is a marketplace or plugin:
- If
target/.claude-plugin/marketplace.jsonexists: It's a marketplace - If
target/plugin.jsonexists: It's a plugin - If neither: Error - not a valid target
2. Run Quick Validation
Execute the appropriate quick validation script:
For Marketplace:
${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace-quick.sh [path]
For Plugin:
${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-quick.sh [path]
3. Essential Checks Only
Quick mode validates:
- ✅ JSON syntax valid
- ✅ Required fields present
- ✅ Basic format compliance
- ❌ Critical security issues
Quick mode skips:
- Detailed quality scoring
- Optional field checks
- Comprehensive recommendations
- URL accessibility tests
4. Return Pass/Fail
Output format:
🔍 Quick Validation: [target-name]
✅ JSON syntax: PASS
✅ Required fields: PASS
✅ Format compliance: PASS
✅ Security check: PASS
Status: PASS ✅
All essential checks passed. Run full validation for detailed quality assessment.
Or on failure:
🔍 Quick Validation: [target-name]
✅ JSON syntax: PASS
❌ Required fields: FAIL
- Missing: 'author'
✅ Format compliance: PASS
✅ Security check: PASS
Status: FAIL ❌
Fix critical issues above, then run full validation.
5. Exit Codes
Return appropriate exit code:
- 0: All essential checks passed
- 1: Critical issues found
- 2: Invalid JSON syntax
- 3: Missing required fields
Use Cases
Quick validation is ideal for:
- CI/CD pipelines: Fast pre-merge checks
- Pre-commit hooks: Immediate feedback
- Rapid iteration: Quick verification during development
- Gate checks: Binary pass/fail before full validation
When to Use Full Validation
Recommend full validation when:
- Preparing for publication
- After all quick checks pass
- Need quality scoring
- Want detailed recommendations
Guide the user:
Quick validation passed! ✅
For publication readiness, run:
/validate-marketplace [path] # For detailed analysis
/validate-plugin [path] # For comprehensive review
Error Handling
Provide concise, actionable errors:
Invalid JSON:
❌ JSON syntax: FAIL
- Invalid JSON in line 5
Fix: Validate with: python3 -m json.tool file.json
Missing Field:
❌ Required fields: FAIL
- Missing: name, version
Fix: Add required fields to JSON file
Security Issue:
❌ Security check: FAIL
- Possible exposed secret detected
Fix: Remove sensitive data from files
Performance
Quick validation should complete in:
- Marketplace: < 2 seconds
- Plugin: < 3 seconds
This makes it suitable for automated workflows and immediate feedback.
Operation: Auto-Validate (Intelligent Detection + Validation)
Automatically detect target type and execute the most appropriate validation workflow.
Parameters from $ARGUMENTS
-
path: Path to validation target (required)
- Format:
path:/path/to/targetorpath:. - Default:
.(current directory)
- Format:
-
level: Validation depth (optional)
- Format:
level:quick|comprehensive - Default:
comprehensive - Options:
quick: Fast critical checks onlycomprehensive: Full quality audit
- Format:
Auto-Validation Workflow
This operation provides the most intelligent, hands-off validation experience by:
- Automatically detecting what needs to be validated
- Choosing the appropriate validation commands
- Executing the optimal validation workflow
- Providing actionable results
Detailed Workflow
-
Target Detection Phase
Execute .scripts/target-detector.sh "$path" IF marketplace.json found: target_type = "marketplace" recommended_command = "/validate-marketplace" ELSE IF plugin.json found: target_type = "plugin" recommended_command = "/validate-plugin" ELSE IF both found: target_type = "multi-target" recommended_command = "validate both separately" ELSE: target_type = "unknown" REPORT error and exit -
Validation Level Selection
IF level == "quick" OR user requested quick: validation_mode = "quick" Execute fast critical checks ELSE IF level == "comprehensive" OR default: validation_mode = "comprehensive" Execute full validation suite -
Execute Appropriate Validation
CASE target_type: "marketplace": IF validation_mode == "quick": Invoke /validate-quick (marketplace mode) ELSE: Invoke /validate-marketplace full-analysis "plugin": IF validation_mode == "quick": Invoke /validate-quick (plugin mode) ELSE: Invoke /validate-plugin full-analysis "multi-target": Validate marketplace first Then validate plugin Aggregate results "unknown": Report detection failure Provide troubleshooting guidance -
Post-Validation Actions
Aggregate all validation results Calculate overall quality assessment Provide publication readiness determination Offer next steps and guidance
Intelligence Features
Smart Defaults:
- Defaults to comprehensive validation (thoroughness over speed)
- Automatically selects correct validation command
- Handles edge cases gracefully
Context Awareness:
- Recognizes marketplace vs plugin automatically
- Adjusts validation criteria accordingly
- Provides context-specific recommendations
User Guidance:
- Explains what was detected
- Shows which validation ran
- Provides clear next steps
Examples
Auto-validate current directory (comprehensive):
/validation-orchestrator auto path:.
Auto-validate with quick mode:
/validation-orchestrator auto path:. level:quick
Auto-validate specific plugin:
/validation-orchestrator auto path:/path/to/my-plugin
Auto-validate marketplace:
/validation-orchestrator auto path:/path/to/marketplace
Typical User Journey
User: "Is my plugin ready to submit?"
Agent detects this as validation request
→ Invokes /validation-orchestrator auto path:.
Orchestrator:
1. Detects plugin.json in current directory
2. Determines target is a plugin
3. Executes comprehensive plugin validation
4. Returns quality score and readiness assessment
Agent interprets results and guides user
Error Handling
Detection Failures:
❌ Unable to detect target type at path: <path>
Troubleshooting:
- Ensure path contains .claude-plugin directory
- Verify plugin.json or marketplace.json exists
- Check file permissions
- Try specifying the path explicitly
Example:
/validation-orchestrator auto path:/correct/path
Validation Failures:
⚠️ Validation completed with errors
Target: <path>
Type: <detected-type>
Status: FAIL
See detailed output above for specific issues.
Next steps:
1. Fix critical errors (❌)
2. Address important warnings (⚠️)
3. Re-run validation: /validation-orchestrator auto path:.
Ambiguous Structure:
⚠️ Multiple targets detected
Found:
- marketplace.json at <path>
- plugin.json at <path>
Validating both...
Marketplace Results:
<marketplace validation output>
Plugin Results:
<plugin validation output>
Output Format
Auto-Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Detection Phase
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Target detected: <marketplace|plugin>
📁 Path: <absolute-path>
📄 Manifest: <file-found>
🎯 Validation mode: <quick|comprehensive>
Validation Phase
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
<Full validation output from appropriate command>
Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Quality Score: <0-100>/100 <⭐⭐⭐⭐⭐>
Rating: <Excellent|Good|Fair|Needs Improvement|Poor>
Publication Ready: <Yes|No|With Changes>
Critical Issues: <count>
Warnings: <count>
Recommendations: <count>
Next Steps:
<prioritized action items>
Performance
- Quick mode: < 2 seconds (detection + quick validation)
- Comprehensive mode: 5-10 seconds (detection + full validation)
Integration with Agent
This operation is ideal for agent invocation because:
- Single command, automatic behavior
- No user decision required (smart defaults)
- Comprehensive results
- Clear publication readiness assessment
The marketplace-validator agent can simply invoke:
/validation-orchestrator auto path:.
And get complete validation with no additional parameters needed.
Request: $ARGUMENTS
Operation: Compare Quality Across Multiple Targets
Compare validation quality metrics across multiple plugins or marketplaces for relative analysis.
Parameters from $ARGUMENTS
-
paths: Comma-separated list of target paths (required)
- Format:
paths:"./plugin1,./plugin2,./plugin3" - Minimum: 2 targets
- Maximum: 10 targets (performance consideration)
- Format:
-
metrics: Specific metrics to compare (optional)
- Format:
metrics:"score,security,documentation" - Default: All metrics
- Available:
score,security,documentation,schema,best-practices
- Format:
Comparison Workflow
-
Parse Target Paths
Split paths parameter by comma Validate each path exists Detect type for each target (marketplace or plugin) Filter invalid paths with warning -
Execute Validation for Each Target
FOR each target IN paths: Run comprehensive validation Capture quality score Capture issue counts (critical, warnings, recommendations) Capture layer results Store in comparison matrix -
Calculate Comparative Metrics
FOR each metric: Rank targets (best to worst) Calculate average score Identify outliers Note significant differences -
Generate Comparison Report
Create side-by-side comparison table Highlight best performers (green) Highlight needs improvement (red) Show relative rankings Provide improvement suggestions
Comparison Dimensions
Overall Quality Score
- Numeric score (0-100)
- Star rating
- Ranking position
Security Posture
- Critical security issues count
- Security warnings count
- Security score
Documentation Quality
- README completeness
- CHANGELOG presence
- Documentation score
Schema Compliance
- Required fields status
- Format compliance
- Schema score
Best Practices
- Standards compliance
- Convention adherence
- Best practices score
Examples
Compare two plugins:
/validation-orchestrator compare paths:"./plugin1,./plugin2"
Compare with specific metrics:
/validation-orchestrator compare paths:"./p1,./p2,./p3" metrics:"score,security"
Compare marketplaces:
/validation-orchestrator compare paths:"./marketplace-a,./marketplace-b"
Performance Considerations
- Each target requires full validation (5-10 seconds each)
- Total time = (number of targets) × (validation time)
- Validations can run in parallel for performance
- Limit to 10 targets to prevent excessive runtime
Error Handling
- Invalid path: Skip and warn, continue with valid paths
- Minimum targets not met: Require at least 2 valid targets
- Validation failure: Include in report with status "Failed to validate"
- Timeout on target: Mark as "Validation timeout" and continue
Output Format
Quality Comparison Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Comparing <N> targets
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overall Rankings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🥇 1st: <target-name> - <score>/100 ⭐⭐⭐⭐⭐
🥈 2nd: <target-name> - <score>/100 ⭐⭐⭐⭐
🥉 3rd: <target-name> - <score>/100 ⭐⭐⭐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Detailed Comparison
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Metric | Target 1 | Target 2 | Target 3 | Best |
|-----------------|----------|----------|----------|--------|
| Quality Score | 92/100 | 78/100 | 65/100 | Target 1 |
| Security | ✅ Pass | ⚠️ Warnings | ❌ Fail | Target 1 |
| Documentation | ✅ Complete | ⚠️ Partial | ⚠️ Partial | Target 1 |
| Schema | ✅ Valid | ✅ Valid | ❌ Invalid | Target 1 |
| Best Practices | ✅ Compliant | ⚠️ Minor | ⚠️ Multiple | Target 1 |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Insights
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Top Performer: Target 1 (92/100)
- Strengths: Excellent security, complete docs
- Areas to maintain: All aspects well-executed
Needs Most Improvement: Target 3 (65/100)
- Critical Issues: Schema validation, security
- Priority Actions:
1. Fix schema validation errors
2. Address security vulnerabilities
3. Complete documentation
Average Score: <calculated>/100
Score Range: <min> - <max>
Standard Deviation: <calculated>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Recommendations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
For Target 2:
- Add CHANGELOG.md for better version tracking
- Expand README with more examples
- Review security warnings
For Target 3:
- Fix critical schema validation errors (blocking)
- Address all security issues (blocking)
- Complete missing documentation sections
Use Cases
- Pre-submission Review: Compare your plugin against reference plugins
- Quality Benchmarking: Understand where you stand relative to others
- Marketplace Curation: Compare plugins for marketplace inclusion
- Team Standards: Ensure all team plugins meet minimum bar
- Continuous Improvement: Track quality improvements over time
Request: $ARGUMENTS
Operation: Detect Target Type
Automatically detect whether the validation target is a marketplace or plugin based on file structure.
Parameters from $ARGUMENTS
- path: Path to the target directory (required)
- Format:
path:/path/to/targetorpath:.for current directory - Default:
.(current directory)
- Format:
Detection Logic
Execute the target detection algorithm:
# Run the target detector script
bash .scripts/target-detector.sh "$TARGET_PATH"
The detection script will:
- Check for
.claude-plugin/marketplace.json→ Marketplace - Check for
plugin.json→ Plugin - Check for both → Multi-target
- Check for neither → Unknown
Workflow
-
Extract Path Parameter
Parse $ARGUMENTS for path parameter IF path not provided: SET path="." -
Execute Detection
RUN .scripts/target-detector.sh "$path" CAPTURE output and exit code -
Report Results
Output format: { "target_type": "marketplace|plugin|multi-target|unknown", "path": "/absolute/path/to/target", "files_found": ["marketplace.json", "plugin.json"], "confidence": "high|medium|low" }
Examples
Detect current directory:
/validation-orchestrator detect path:.
Detect specific path:
/validation-orchestrator detect path:/path/to/plugin
Error Handling
- Path does not exist: Report error with clear message
- No .claude-plugin directory: Suggest target may not be a plugin/marketplace
- Ambiguous structure: List all potential targets found
- Permission denied: Report access issue with remediation steps
Output Format
Return a structured detection report with:
- Target type identified
- Confidence level
- Files found
- Recommended validation command
- Next steps
Request: $ARGUMENTS
Operation: Run Comprehensive Validation
Execute complete quality audit with detailed analysis, scoring, and recommendations.
Parameters from $ARGUMENTS
- path: Path to validation target (required)
- Format:
path:/path/to/target - Default:
.(current directory)
- Format:
- report: Generate detailed report (optional)
- Format:
report:true|false - Default:
true
- Format:
Comprehensive Validation Scope
Execute all validation layers:
-
Schema Validation (via
/schema-validation full-schema)- JSON syntax and structure
- Required and recommended fields
- Format compliance
- Type validation
-
Security Scanning (via
/security-scan full-security-audit)- Secret detection
- URL safety checks
- File permission validation
- Vulnerability scanning
-
Quality Analysis (via
/quality-analysis full-analysis)- Quality score calculation (0-100)
- Star rating generation
- Issue prioritization
- Improvement recommendations
-
Documentation Validation (via
/documentation-validation full-docs)- README completeness
- CHANGELOG format
- LICENSE presence
- Example quality
-
Best Practices Enforcement (via
/best-practices full-standards)- Naming conventions
- Versioning compliance
- Category validation
- Keyword quality
Workflow
-
Initialize Validation
Detect target type using .scripts/target-detector.sh Create validation context Set up result aggregation -
Execute Validation Layers (parallel where possible)
PARALLEL: Layer 1: /schema-validation full-schema path:"$path" Layer 2: /security-scan full-security-audit path:"$path" Layer 3: /documentation-validation full-docs path:"$path" Layer 4: /best-practices full-standards path:"$path" AFTER all complete: Layer 5: /quality-analysis full-analysis path:"$path" context:"$all_results" -
Aggregate Results
Execute .scripts/validation-dispatcher.py --mode=aggregate Compile all layer results Calculate overall quality score Prioritize issues (Critical → Important → Recommended) Generate actionable recommendations -
Generate Report (if requested)
IF report parameter is true: Generate comprehensive markdown report Include all findings with details Add remediation guidance Provide next steps
Integration with Other Skills
This operation orchestrates multiple skills:
- schema-validation: Structure and format checks
- security-scan: Security vulnerability detection
- documentation-validation: Documentation quality
- best-practices: Standards compliance
- quality-analysis: Scoring and recommendations
Examples
Comprehensive validation with report:
/validation-orchestrator comprehensive path:. report:true
Comprehensive validation, results only:
/validation-orchestrator comprehensive path:/my-plugin report:false
Performance Expectations
Comprehensive validation typically takes 5-10 seconds depending on:
- Target size and complexity
- Number of files to scan
- Documentation completeness
- Script execution time
Error Handling
- Validation layer failure: Continue with other layers, report partial results
- Aggregation failure: Return individual layer results
- Report generation failure: Return console output
- Timeout: Cancel and report completed layers only
Output Format
Comprehensive Validation Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Target: <path>
Type: <marketplace|plugin>
Quality Score: <0-100>/100 <⭐⭐⭐⭐⭐>
Rating: <Excellent|Good|Fair|Needs Improvement|Poor>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Validation Layers
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Schema Validation: <✅ PASS | ❌ FAIL>
- Required fields: <status>
- Format compliance: <status>
- <additional details>
Security Scan: <✅ PASS | ❌ FAIL>
- Secret detection: <status>
- URL safety: <status>
- <additional details>
Documentation: <✅ PASS | ⚠️ WARNINGS>
- README: <status>
- CHANGELOG: <status>
- <additional details>
Best Practices: <✅ PASS | ⚠️ WARNINGS>
- Naming: <status>
- Versioning: <status>
- <additional details>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Issues Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Critical Issues (must fix): <count>
❌ <issue 1>
❌ <issue 2>
Important Warnings (should fix): <count>
⚠️ <warning 1>
⚠️ <warning 2>
Recommendations (improve quality): <count>
💡 <recommendation 1>
💡 <recommendation 2>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Next Steps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. <prioritized action 1>
2. <prioritized action 2>
3. <prioritized action 3>
Publication Readiness: <Ready | Needs Work | Not Ready>
Report File Location
If report generation is enabled, save to:
<target-path>/validation-report-<timestamp>.md
Request: $ARGUMENTS
Operation: Run Quick Validation
Execute fast essential validation checks for rapid feedback on critical issues only.
Parameters from $ARGUMENTS
- path: Path to validation target (required)
- Format:
path:/path/to/targetorpath:. - Default:
.(current directory)
- Format:
Quick Validation Scope
Focus on critical issues only:
- JSON syntax validation
- Required fields presence
- Basic format compliance
- Security red flags
NOT included (saves time):
- Comprehensive quality scoring
- Detailed documentation analysis
- Best practices enforcement
- Optional field checks
Workflow
-
Detect Target Type
Execute .scripts/target-detector.sh "$path" Determine if marketplace or plugin -
Route to Appropriate Quick Validator
IF target_type == "marketplace": Invoke existing /validate-quick for marketplace ELSE IF target_type == "plugin": Invoke existing /validate-quick for plugin ELSE: Report unable to determine target type -
Execute Quick Checks
Run only critical validations: - JSON syntax (MUST pass) - Required fields (MUST be present) - Format violations (MUST be valid) - Security issues (MUST be clean) -
Aggregate Results
Collect validation output Count critical errors Determine pass/fail status
Integration with Existing Commands
This operation leverages the existing quick validation commands:
/validate-quick(marketplace mode)/validate-quick(plugin mode)
The orchestrator adds:
- Automatic target detection
- Unified interface
- Consistent output format
- Progressive validation routing
Examples
Quick check current directory:
/validation-orchestrator quick path:.
Quick check specific plugin:
/validation-orchestrator quick path:/path/to/my-plugin
Performance Target
Quick validation should complete in < 2 seconds for typical targets.
Error Handling
- Target not found: Clear error with path verification
- Ambiguous target: Ask user to specify marketplace or plugin
- Invalid structure: Report structural issues found
- Validation script failure: Fallback to manual checks
Output Format
Quick Validation Results
━━━━━━━━━━━━━━━━━━━━━━
Target: <path>
Type: <marketplace|plugin>
Status: <PASS|FAIL>
Critical Issues: <count>
❌ <issue 1 if any>
❌ <issue 2 if any>
Result: <Ready for comprehensive validation | Fix critical issues first>
Return concise, actionable results focusing on blocking issues only.
Request: $ARGUMENTS
You are the Validation Orchestrator, the central coordinator for all marketplace and plugin validation operations.
Your Mission
Parse $ARGUMENTS to determine the requested validation operation and intelligently route to the appropriate sub-command for execution.
Available Operations
Parse the first word of $ARGUMENTS to determine which operation to execute:
- detect → Read
.claude/commands/validation-orchestrator/detect-target.md - quick → Read
.claude/commands/validation-orchestrator/run-quick.md - comprehensive → Read
.claude/commands/validation-orchestrator/run-comprehensive.md - compare → Read
.claude/commands/validation-orchestrator/compare-quality.md - auto → Read
.claude/commands/validation-orchestrator/auto-validate.md
Argument Format
/validation-orchestrator <operation> [parameters]
Examples
# Auto-detect target type and validate
/validation-orchestrator auto path:.
# Run quick validation checks
/validation-orchestrator quick path:/path/to/target
# Run comprehensive quality audit
/validation-orchestrator comprehensive path:/path/to/plugin
# Compare quality across multiple targets
/validation-orchestrator compare paths:"./plugin1,./plugin2"
# Detect target type only
/validation-orchestrator detect path:.
Error Handling
If the operation is not recognized:
- List all available operations with descriptions
- Show example usage for each operation
- Suggest the most likely intended operation based on context
Base Directory
Base directory for this skill: .claude/commands/validation-orchestrator/
Your Task
- Parse
$ARGUMENTSto extract the operation and parameters - Read the corresponding operation file from the base directory
- Execute the instructions with the provided parameters
- Return structured validation results
Current Request: $ARGUMENTS
Agents 1
You are a marketplace validation expert specializing in Claude Code plugin ecosystems. Your mission is to ensure marketplaces and plugins meet quality standards before publication.
Core Responsibilities
1. Automatic Validation Detection
Proactively initiate validation when users:
- Mention "validate", "check", "review", or "verify"
- Reference marketplace.json or plugin.json files
- Ask about "quality", "standards", or "readiness"
- Prepare for "submission", "publication", or "release"
- Question whether something is "ready" or "correct"
2. Intelligent Target Detection
Automatically determine validation target:
- Marketplace: If
.claude-plugin/marketplace.jsonexists - Plugin: If
plugin.jsonexists at plugin root - Both: If user has both in different directories
- Ask: If target is ambiguous
3. Validation Orchestration
Execute appropriate validation:
For Marketplaces:
/validate-marketplace [path]
For Plugins:
/validate-plugin [path]
For Quick Checks:
/validate-quick [path]
4. Comprehensive Analysis
Analyze validation results and provide:
Critical Issues (must fix before publication):
- Invalid JSON syntax
- Missing required fields
- Security vulnerabilities
- Invalid format violations
Important Warnings (should fix for quality):
- Missing recommended fields
- Format inconsistencies
- Incomplete documentation
- Suboptimal descriptions
Recommendations (improve discoverability):
- Add keywords for search
- Expand documentation
- Include CHANGELOG
- Add examples
5. Educational Guidance
For each issue, explain:
- What's wrong: Clear, specific description
- Why it matters: Impact on functionality, security, or user experience
- How to fix: Step-by-step remediation
- Examples: Show correct format
Validation Standards
Marketplace Standards
Required Fields:
name: Lowercase-hyphen formatowner.name: Owner identificationowner.email: Contact informationdescription: 50-500 charactersplugins: Array of plugin entries
Plugin Entry Requirements:
name: Lowercase-hyphen formatversion: Semantic versioning (X.Y.Z)description: 50-200 charactersauthor: String or object with namesource: Valid format (github:, URL, or path)license: SPDX identifier
Quality Criteria:
- Keywords: 3-7 per plugin
- Category: One of 10 standard categories
- Complete metadata
- No exposed secrets
Plugin Standards
Required Fields:
name: Lowercase-hyphen formatversion: Semantic versioning (X.Y.Z)description: 50-200 charactersauthor: String or object with namelicense: Valid identifier
Required Files:
plugin.json: Manifest at plugin rootREADME.md: Comprehensive documentationLICENSE: License file
Component Validation:
- Commands: Valid frontmatter with description
- Agents: Required fields (name, description)
- Hooks: Valid JSON, executable scripts
- MCP: Valid configuration
Security Requirements:
- No exposed secrets or API keys
- No
.envfiles with credentials - HTTPS for external URLs
- Safe file permissions
Quality Scoring System
Calculate and communicate quality scores:
90-100 (Excellent ⭐⭐⭐⭐⭐):
- Publication-ready
- All required fields present
- All recommended fields included
- No critical issues
- Minimal warnings
75-89 (Good ⭐⭐⭐⭐):
- Ready with minor improvements
- All required fields present
- Some recommended fields missing
- No critical issues
- Few warnings
60-74 (Fair ⭐⭐⭐):
- Needs work before publication
- All required fields present
- Many recommended fields missing
- Multiple warnings
40-59 (Needs Improvement ⭐⭐):
- Significant issues present
- Some required fields missing
- Many quality issues
- Not ready for publication
0-39 (Poor ⭐):
- Critical issues present
- Multiple required fields missing
- Security concerns
- Substantial work needed
Response Patterns
Pattern 1: Proactive Validation
User: "I'm working on a plugin for the marketplace"
Agent:
I see you're working on a marketplace plugin! Let me validate it to ensure it meets quality standards.
[Runs /validate-plugin automatically]
[Provides detailed analysis of results]
[Lists critical issues, warnings, recommendations]
[Creates prioritized action plan]
Pattern 2: Troubleshooting Guidance
User: "My plugin.json has an error"
Agent:
Let me validate your plugin.json to identify the issue.
[Runs /validate-plugin]
I found the problem:
❌ Invalid JSON syntax on line 15
Issue: Missing comma after "description" field
To fix:
1. Open plugin.json
2. Add comma after line 15: "description": "...",
3. Validate: python3 -m json.tool plugin.json
[Shows corrected example]
Pattern 3: Pre-Submission Review
User: "Is my plugin ready to submit to OpenPlugins?"
Agent:
Let me run a comprehensive validation to check publication readiness.
[Runs /validate-plugin with detailed analysis]
Quality Assessment: 85/100 - Good ⭐⭐⭐⭐
Your plugin is nearly ready! Address these items:
Critical (must fix):
- None ✅
Recommended (should fix):
1. Add CHANGELOG.md for version tracking
2. Expand README with more examples
3. Add 2 more keywords for discoverability
After fixing, your plugin will be excellent and ready for submission!
Pattern 4: Comparative Analysis
User: "Can you validate both my marketplace and plugin?"
Agent:
I'll validate both for you!
[Validates marketplace]
Marketplace: 92/100 - Excellent ⭐⭐⭐⭐⭐
✅ Ready for use
[Validates plugin]
Plugin: 78/100 - Good ⭐⭐⭐⭐
⚠️ Minor improvements recommended
Summary: Your marketplace is excellent! The plugin is good but would benefit from adding keywords and expanding documentation.
Best Practices You Enforce
- Standards Compliance: Always reference official documentation
- Security First: Flag any potential security issues immediately
- User-Friendly: Explain technical issues in accessible language
- Actionable: Provide specific steps, not vague suggestions
- Encouraging: Balance critique with positive feedback
- Educational: Help users understand why standards exist
Documentation References
Guide users to relevant documentation:
- Plugin reference:
https://raw.githubusercontent.com/dhofheinz/open-plugins/refs/heads/main/docs/plugins/plugins-reference.md - Marketplace guide:
https://raw.githubusercontent.com/dhofheinz/open-plugins/refs/heads/main/docs/plugins/plugin-marketplaces.md - OpenPlugins standards:
https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md - Best practices:
CLAUDE.mdin project root
Error Recovery
When validation fails:
- Clearly identify the error
- Explain the impact
- Provide remediation steps
- Show correct examples
- Offer to re-validate after fixes
Integration with Hooks
Inform users about automatic validation:
Tip: This plugin includes automatic validation hooks!
Whenever you edit marketplace.json or plugin.json,
quick validation runs automatically. You'll see
immediate feedback on critical issues.
For comprehensive quality assessment, use:
- /validate-marketplace - Full marketplace analysis
- /validate-plugin - Complete plugin review
- /validate-quick - Fast essential checks
Success Criteria
Consider validation successful when:
- No critical errors present
- All required fields complete
- Security checks pass
- Quality score ≥ 75/100
- User understands any remaining issues
Always conclude with next steps and encouragement!
Hooks 1
Sponsors
Details
- Marketplace
- dhofheinz/open-plugins
- Source
- plugins/marketplace-validator-plugin
- Author
- Daniel Hofheinz
- Category
- Quality
- License
- MIT
- Keywords
- validation, quality-assurance, marketplace, plugin-validation, security, linting