260 lines
7.3 KiB
Markdown
260 lines
7.3 KiB
Markdown
# Quality Validation Checklist
|
|
|
|
Generated skills must pass all validation criteria before installation. This checklist ensures compliance with Anthropic's skill standards and Connor's quality requirements.
|
|
|
|
## 1. YAML Frontmatter Validation
|
|
|
|
### Required Fields
|
|
- [ ] `name` field present and valid
|
|
- Max 64 characters
|
|
- Lowercase, numbers, hyphens only
|
|
- No reserved words (skill, claude, anthropic)
|
|
- Matches directory name
|
|
|
|
- [ ] `description` field present and valid
|
|
- Max 1024 characters
|
|
- Non-empty
|
|
- No XML/HTML tags
|
|
- Action-oriented (starts with verb)
|
|
|
|
### Description Quality
|
|
- [ ] Contains trigger phrase
|
|
- "Use PROACTIVELY when..." OR
|
|
- "Use when..." OR
|
|
- "Guides..." OR
|
|
- "Analyzes..." OR
|
|
- Similar action verb
|
|
|
|
- [ ] Describes clear value/benefit
|
|
- What problem does it solve?
|
|
- What outcome does it produce?
|
|
|
|
- [ ] Appropriate for skill category
|
|
- Aligns with insight category
|
|
- Matches skill type (tooling/analysis/productivity)
|
|
|
|
### Optional Fields (if present)
|
|
- [ ] `allowed-tools` (Claude Code only)
|
|
- Valid tool names only
|
|
- No duplicates
|
|
|
|
- [ ] Custom fields are reasonable
|
|
- `version`, `author`, `category` are common
|
|
|
|
## 2. File Structure Validation
|
|
|
|
### Required Files
|
|
- [ ] `SKILL.md` exists and is non-empty
|
|
- [ ] `README.md` exists and is non-empty
|
|
- [ ] `plugin.json` exists and is valid JSON
|
|
- [ ] `CHANGELOG.md` exists with v0.1.0 entry
|
|
|
|
### Optional Files (based on complexity)
|
|
- [ ] `data/` directory if complexity >= standard
|
|
- [ ] `data/insights-reference.md` if multiple insights
|
|
- [ ] `examples/` directory if code examples present
|
|
- [ ] `templates/` directory if actionable checklists exist
|
|
|
|
### File Size Limits
|
|
- [ ] SKILL.md < 500 lines (recommend splitting if larger)
|
|
- [ ] No single file > 1000 lines
|
|
- [ ] Total skill size < 1MB
|
|
|
|
## 3. SKILL.md Content Quality
|
|
|
|
### Structure
|
|
- [ ] Clear heading hierarchy (h1 → h2 → h3)
|
|
- [ ] No skipped heading levels
|
|
- [ ] Consistent formatting throughout
|
|
|
|
### Required Sections
|
|
- [ ] Overview/Introduction
|
|
- What the skill does
|
|
- When to use it
|
|
|
|
- [ ] Workflow or Phases
|
|
- Clear step-by-step instructions
|
|
- Numbered or bulleted steps
|
|
- Logical progression
|
|
|
|
- [ ] Examples (if applicable)
|
|
- Concrete use cases
|
|
- Expected outputs
|
|
|
|
### Content Quality
|
|
- [ ] Clear, concise language
|
|
- [ ] No ambiguous pronouns ("it", "this", "that" without context)
|
|
- [ ] Consistent terminology (no mixing synonyms)
|
|
- [ ] Action-oriented instructions (imperative mood)
|
|
|
|
### Progressive Disclosure
|
|
- [ ] SKILL.md serves as table of contents
|
|
- [ ] Detailed content in separate files (data/, examples/)
|
|
- [ ] References are one level deep (no nested references)
|
|
|
|
## 4. Insight Integration Quality
|
|
|
|
### Insight Attribution
|
|
- [ ] Original insights preserved in `data/insights-reference.md`
|
|
- [ ] Insights properly dated and sourced
|
|
- [ ] Session metadata included
|
|
|
|
### Content Transformation
|
|
- [ ] Insights converted to actionable workflow steps
|
|
- [ ] Problem-solution structure maintained
|
|
- [ ] Code examples extracted to examples/
|
|
- [ ] Best practices highlighted in Important Reminders
|
|
|
|
### Deduplication
|
|
- [ ] No duplicate content between skill files
|
|
- [ ] Cross-references used instead of duplication
|
|
- [ ] Consolidated similar points
|
|
|
|
## 5. Pattern Adherence
|
|
|
|
### Selected Pattern (phase-based/mode-based/validation)
|
|
- [ ] Pattern choice justified by insight content
|
|
- [ ] Pattern correctly implemented
|
|
- [ ] Section structure matches pattern conventions
|
|
|
|
### Workflow Logic
|
|
- [ ] Phases/modes are sequential or parallel as appropriate
|
|
- [ ] Each phase has clear purpose
|
|
- [ ] Prerequisites stated upfront
|
|
- [ ] Expected outputs defined
|
|
|
|
### Error Handling
|
|
- [ ] Common pitfalls documented
|
|
- [ ] Troubleshooting guidance included
|
|
- [ ] Failure recovery steps provided
|
|
|
|
## 6. README.md Quality
|
|
|
|
### Required Sections
|
|
- [ ] Brief overview (1-2 sentences)
|
|
- [ ] When to use (trigger phrases)
|
|
- [ ] Quick start example
|
|
- [ ] Installation instructions (if not standard)
|
|
|
|
### Clarity
|
|
- [ ] User-focused (not developer-focused)
|
|
- [ ] Examples are copy-pasteable
|
|
- [ ] Screenshots/diagrams if beneficial
|
|
|
|
## 7. plugin.json Validation
|
|
|
|
### JSON Validity
|
|
- [ ] Valid JSON syntax
|
|
- [ ] No trailing commas
|
|
- [ ] Proper escaping
|
|
|
|
### Required Fields
|
|
- [ ] `name` matches SKILL.md frontmatter
|
|
- [ ] `version` follows semver (0.1.0 for new skills)
|
|
- [ ] `description` matches SKILL.md frontmatter
|
|
- [ ] `type` is "skill"
|
|
|
|
### Optional Fields (if present)
|
|
- [ ] `author` is reasonable string
|
|
- [ ] `category` is valid (tooling/analysis/productivity/devops)
|
|
- [ ] `tags` are relevant keywords
|
|
|
|
## 8. Code Quality (if skill includes examples)
|
|
|
|
### Code Examples
|
|
- [ ] Syntax highlighting specified (```language)
|
|
- [ ] Code is complete and runnable
|
|
- [ ] No placeholder variables (unless clearly marked)
|
|
- [ ] Comments explain non-obvious logic
|
|
|
|
### Best Practices
|
|
- [ ] Follows language conventions
|
|
- [ ] No security vulnerabilities
|
|
- [ ] No hardcoded credentials
|
|
- [ ] Error handling demonstrated
|
|
|
|
## 9. Accessibility & Usability
|
|
|
|
### Trigger Phrases
|
|
- [ ] Multiple trigger phrases provided
|
|
- [ ] Phrases are natural language
|
|
- [ ] Covers different ways users might ask
|
|
- [ ] PROACTIVELY triggers are specific (not too broad)
|
|
|
|
### Searchability
|
|
- [ ] Skill name reflects function
|
|
- [ ] Description contains relevant keywords
|
|
- [ ] Tags (if present) aid discovery
|
|
|
|
### User Guidance
|
|
- [ ] Clear next steps after each phase
|
|
- [ ] Decision points clearly marked
|
|
- [ ] Optional vs. required steps distinguished
|
|
|
|
## 10. Edge Cases & Robustness
|
|
|
|
### Input Handling
|
|
- [ ] Handles missing/malformed input gracefully
|
|
- [ ] Validates prerequisites before execution
|
|
- [ ] Provides helpful error messages
|
|
|
|
### Project Variability
|
|
- [ ] Handles different project structures
|
|
- [ ] Works with monorepos and single packages
|
|
- [ ] Adapts to different tech stacks
|
|
|
|
### Maintenance
|
|
- [ ] No hardcoded paths (use relative or user-provided)
|
|
- [ ] No assumptions about environment
|
|
- [ ] Graceful degradation if optional tools unavailable
|
|
|
|
## 11. Insight-Specific Validation
|
|
|
|
### Quality Filter
|
|
- [ ] Only high-quality insights converted
|
|
- Actionable (not just informational)
|
|
- Generally applicable (not project-specific)
|
|
- Valuable (solves real problem)
|
|
|
|
### Relevance
|
|
- [ ] Skill solves problem not covered by existing skills
|
|
- [ ] No duplication with skill-creator, sub-agent-creator, etc.
|
|
- [ ] Unique value proposition clear
|
|
|
|
### Scope
|
|
- [ ] Skill is focused (does one thing well)
|
|
- [ ] Not too broad (overwhelming)
|
|
- [ ] Not too narrow (trivial)
|
|
|
|
## Scoring
|
|
|
|
### Critical (must pass all)
|
|
All items in sections 1-2 (Frontmatter, File Structure)
|
|
|
|
### High Priority (must pass 90%+)
|
|
Sections 3-5 (Content Quality, Insight Integration, Pattern Adherence)
|
|
|
|
### Medium Priority (must pass 80%+)
|
|
Sections 6-9 (README, plugin.json, Code Quality, Usability)
|
|
|
|
### Optional (nice to have)
|
|
Sections 10-11 (Edge Cases, Insight-Specific)
|
|
|
|
## Auto-Fix Opportunities
|
|
|
|
Some issues can be auto-corrected:
|
|
- [ ] Trim description to 1024 chars
|
|
- [ ] Convert skill name to lowercase kebab-case
|
|
- [ ] Add missing CHANGELOG.md with v0.1.0
|
|
- [ ] Generate basic README.md from SKILL.md overview
|
|
- [ ] Validate and pretty-print JSON files
|
|
|
|
## Manual Review Required
|
|
|
|
Some issues require user decision:
|
|
- Ambiguous trigger phrases
|
|
- Pattern selection uncertainty
|
|
- Multiple valid skill name options
|
|
- Content organization choices
|
|
- Category assignment conflicts
|