gh-cskiro-claudex/skills/meta/skill-creator/data/quality-checklist.md

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