212 lines
6.0 KiB
Markdown
212 lines
6.0 KiB
Markdown
# Skill Quality Checklist
|
|
|
|
Use this checklist to validate skill quality before submission or installation.
|
|
|
|
## Required Files (Critical)
|
|
|
|
- [ ] `SKILL.md` exists with valid YAML frontmatter
|
|
- [ ] `README.md` exists with usage examples
|
|
- [ ] `plugin.json` exists with valid JSON
|
|
- [ ] `CHANGELOG.md` exists with v0.1.0 entry
|
|
|
|
## SKILL.md Validation
|
|
|
|
### Frontmatter
|
|
- [ ] `name` field present (kebab-case)
|
|
- [ ] `version` field present (0.1.0 for new skills)
|
|
- [ ] `description` field present (1-2 sentences)
|
|
- [ ] `author` field present
|
|
|
|
### Required Sections
|
|
- [ ] "Overview" section describes skill capabilities
|
|
- [ ] "When to Use This Skill" with trigger phrases
|
|
- [ ] "When to Use This Skill" with use cases (3-5 items)
|
|
- [ ] "Core Responsibilities" or "Workflow" section
|
|
- [ ] "Success Criteria" or similar completion checklist
|
|
|
|
### Content Quality
|
|
- [ ] No placeholder text like "[TODO]" or "[FILL IN]" (unless marked for user customization)
|
|
- [ ] Trigger phrases are specific and actionable
|
|
- [ ] Use cases clearly describe when to activate skill
|
|
- [ ] Workflow or responsibilities are detailed
|
|
- [ ] No generic programming advice (Claude already knows this)
|
|
|
|
## README.md Validation
|
|
|
|
### Structure
|
|
- [ ] Title matches skill name
|
|
- [ ] Brief description (1-2 sentences) at top
|
|
- [ ] "Quick Start" section with example
|
|
- [ ] "Installation" instructions
|
|
- [ ] At least 2 usage examples
|
|
|
|
### Content Quality
|
|
- [ ] Examples are concrete and actionable
|
|
- [ ] Installation instructions are clear
|
|
- [ ] Requirements section lists dependencies
|
|
- [ ] Troubleshooting section addresses common issues
|
|
|
|
## plugin.json Validation
|
|
|
|
### Required Fields
|
|
- [ ] `name` matches skill directory name
|
|
- [ ] `version` is valid semver (0.1.0 for new skills)
|
|
- [ ] `description` matches SKILL.md frontmatter
|
|
- [ ] `author` present
|
|
- [ ] `license` is "Apache-2.0"
|
|
- [ ] `homepage` URL is correct
|
|
- [ ] `repository` object present with type and url
|
|
|
|
### Components
|
|
- [ ] `components.agents` array present
|
|
- [ ] At least one agent with `name` and `manifestPath`
|
|
- [ ] `manifestPath` points to "SKILL.md"
|
|
|
|
### Metadata
|
|
- [ ] `metadata.category` is one of: analysis, tooling, productivity, devops
|
|
- [ ] `metadata.status` is "proof-of-concept" for new skills
|
|
- [ ] `metadata.tested` describes testing scope
|
|
|
|
### Keywords
|
|
- [ ] At least 3 keywords present
|
|
- [ ] Keywords are relevant and specific
|
|
- [ ] Keywords aid discoverability (not too generic)
|
|
|
|
## CHANGELOG.md Validation
|
|
|
|
- [ ] Follows "Keep a Changelog" format
|
|
- [ ] Has section for version 0.1.0
|
|
- [ ] Date is present and correct
|
|
- [ ] "Added" section lists initial features
|
|
- [ ] Status section describes testing level
|
|
- [ ] Link to release tag at bottom
|
|
|
|
## Security Validation (Critical)
|
|
|
|
- [ ] No API keys, tokens, or passwords in any file
|
|
- [ ] No database connection strings with credentials
|
|
- [ ] No private keys (PEM format)
|
|
- [ ] No internal IP addresses or infrastructure details
|
|
- [ ] No hardcoded secrets of any kind
|
|
|
|
## Version Control
|
|
|
|
- [ ] `.gitignore` present if skill generates files (like .processed/)
|
|
- [ ] No generated files committed (build artifacts, logs, etc.)
|
|
- [ ] No large binary files (> 1MB)
|
|
|
|
## Naming Conventions
|
|
|
|
- [ ] Skill name is kebab-case (e.g., "skill-name")
|
|
- [ ] Directory name matches skill name
|
|
- [ ] No spaces in names
|
|
- [ ] Name is descriptive and not too generic
|
|
|
|
## Documentation Quality
|
|
|
|
- [ ] All sections are complete (no stubs)
|
|
- [ ] Examples are realistic and helpful
|
|
- [ ] Technical terms are explained or linked
|
|
- [ ] Grammar and spelling are correct
|
|
- [ ] Markdown formatting is valid
|
|
|
|
## Pattern Consistency
|
|
|
|
If skill uses specific pattern:
|
|
|
|
### Mode-Based Skills
|
|
- [ ] "Quick Decision Matrix" present
|
|
- [ ] "Mode Detection Logic" present
|
|
- [ ] Each mode has clear trigger phrases
|
|
- [ ] Modes are distinct and non-overlapping
|
|
|
|
### Phase-Based Skills
|
|
- [ ] Phases are numbered and named
|
|
- [ ] Each phase has clear purpose
|
|
- [ ] Dependencies between phases are documented
|
|
- [ ] Transition criteria are explicit
|
|
|
|
### Validation Skills
|
|
- [ ] Validation sources are documented
|
|
- [ ] Finding structure is consistent
|
|
- [ ] Severity levels are defined
|
|
- [ ] Score calculation is explained
|
|
|
|
### Data Processing Skills
|
|
- [ ] Data flow architecture is documented
|
|
- [ ] Storage strategy is explained
|
|
- [ ] Performance characteristics are listed
|
|
- [ ] Helper scripts are provided
|
|
|
|
## Testing Validation
|
|
|
|
- [ ] Skill can be loaded without errors
|
|
- [ ] Trigger phrases activate the skill
|
|
- [ ] Example workflows complete successfully
|
|
- [ ] No obvious bugs or crashes
|
|
|
|
## User Experience
|
|
|
|
- [ ] Skill purpose is immediately clear
|
|
- [ ] Trigger phrases are intuitive
|
|
- [ ] Workflow is logical and easy to follow
|
|
- [ ] Error messages are helpful
|
|
- [ ] Success criteria are measurable
|
|
|
|
## Scoring
|
|
|
|
**Critical Issues** (Must fix before use):
|
|
- Missing required files
|
|
- Invalid JSON/YAML
|
|
- Security issues (exposed secrets)
|
|
- Skill fails to load
|
|
|
|
**High Priority** (Fix before submission):
|
|
- Incomplete documentation
|
|
- Missing examples
|
|
- Unclear trigger phrases
|
|
- Invalid metadata
|
|
|
|
**Medium Priority** (Improve when possible):
|
|
- Inconsistent formatting
|
|
- Missing optional sections
|
|
- Could use more examples
|
|
- Documentation could be clearer
|
|
|
|
**Low Priority** (Nice to have):
|
|
- Additional examples
|
|
- More detailed explanations
|
|
- Enhanced formatting
|
|
- Extra reference materials
|
|
|
|
## Overall Quality Score
|
|
|
|
Calculate a quality score:
|
|
|
|
```
|
|
Critical Issues: 0 required (any critical issue = fail)
|
|
High Priority: 0-2 acceptable (> 2 needs work)
|
|
Medium Priority: 0-5 acceptable (> 5 needs improvement)
|
|
Low Priority: Any number acceptable
|
|
|
|
Overall Grade:
|
|
- A (90-100): Production ready, excellent quality
|
|
- B (80-89): Good quality, minor improvements
|
|
- C (70-79): Acceptable, some improvements needed
|
|
- D (60-69): Needs work before submission
|
|
- F (< 60): Significant issues, do not submit
|
|
```
|
|
|
|
## Pre-Submission Final Check
|
|
|
|
Before submitting to marketplace:
|
|
|
|
1. [ ] Run through entire checklist
|
|
2. [ ] Test in fresh Claude Code session
|
|
3. [ ] Get peer review if possible
|
|
4. [ ] Verify all links work
|
|
5. [ ] Check for typos and errors
|
|
6. [ ] Confirm no sensitive data
|
|
7. [ ] Verify version is correct
|
|
8. [ ] Update CHANGELOG if needed
|