This skill provides a comprehensive, actionable checklist for evaluating skill file quality. Use it as a gate before publishing, as a review framework for existing skills, and as a training tool for new skill authors. Every criterion is specific and verifiable — no subjective "is it good enough?" judgments.

## Key Points

- Reviewing a skill file before publishing
- Establishing quality standards for a team
- Auditing an existing skill pack for quality
- Training new skill authors on expectations
- Deciding whether a skill needs revision
- Creating automated skill validation pipelines

Skill Quality Checklist

Purpose

This skill provides a comprehensive, actionable checklist for evaluating skill file quality. Use it as a gate before publishing, as a review framework for existing skills, and as a training tool for new skill authors. Every criterion is specific and verifiable — no subjective "is it good enough?" judgments.

The Complete Checklist

Structure (10 points)

□ 1. Valid YAML frontmatter with --- delimiters
     Verify: First line is exactly "---", frontmatter closes with "---"

□ 2. All required frontmatter fields present
     Required: title, category, tags, version
     Verify: Each field has a non-empty value

□ 3. Title is specific and searchable (4-12 words)
     Verify: Contains technology/domain name
     Verify: Someone searching for the topic would find this title
     Fail: "Best Practices", "Advanced Topics", "Guide"

□ 4. Tags array has 3-8 relevant keywords
     Verify: Includes technology name
     Verify: Tags are lowercase kebab-case
     Verify: No duplicate tags

□ 5. Version follows semantic versioning (X.Y.Z)
     Verify: Matches pattern \d+\.\d+\.\d+

□ 6. Single H1 heading matches frontmatter title
     Verify: Only one # heading in the file
     Verify: Text matches title field (or is acceptably close)

□ 7. Purpose section exists immediately after H1
     Verify: ## Purpose is the first H2
     Verify: 2-4 sentences (not a paragraph, not a single sentence)

□ 8. "When to Apply" section exists
     Verify: ## When to Apply (or similar)
     Verify: Contains "Use this skill when:" with bullet points
     Bonus: Contains "Do not use when:" guidance

□ 9. Heading hierarchy is correct
     Verify: No H3 without parent H2
     Verify: No H4 without parent H3
     Verify: No heading level skips (H2 → H4)

□ 10. File length is 100-600 lines
      Under 100: Likely too thin to be useful
      Over 600: Consider splitting into multiple skills

Content Quality (20 points)

□ 11. Purpose clearly states what the skill enables
      Verify: Reader knows after 2 sentences whether this skill
      is relevant to their task
      Fail: Vague purpose that could apply to many skills

□ 12. Content is actionable, not just informational
      Verify: Contains instructions (do X, then Y)
      Verify: Not just a reference page or glossary
      Fail: Purely theoretical content without implementation guidance

□ 13. Content is accurate and current
      Verify: Code examples are correct for stated versions
      Verify: Referenced APIs/tools exist and work as described
      Verify: No deprecated recommendations without noting deprecation

□ 14. Content is original and adds value
      Verify: Not a copy of official documentation
      Verify: Adds practical insight beyond what docs provide
      Verify: Specific to the task, not generic

□ 15. Code examples are correct and complete
      Verify: Code blocks compile/run without modification
      Verify: Language is specified in code fence
      Verify: Imports and dependencies are shown
      Fail: Pseudocode without marking it as pseudocode

□ 16. Code examples are realistic
      Verify: Examples use real-world patterns (not foo/bar)
      Verify: Variable names are descriptive
      Verify: Examples are relevant to the skill's purpose
      Fail: Trivial examples that don't demonstrate the concept

□ 17. Common pitfalls are documented
      Verify: At least 3 specific, common mistakes listed
      Verify: Each pitfall explains WHY it's wrong
      Verify: Each pitfall shows the CORRECT approach
      Fail: Generic warnings without specific guidance

□ 18. Edge cases are addressed
      Verify: Non-obvious scenarios are covered
      Verify: Error conditions are handled
      Verify: Boundary conditions are mentioned
      Fail: Only covers the happy path

□ 19. Content follows a logical progression
      Verify: Simpler concepts before complex ones
      Verify: Each section builds on previous
      Verify: No forward references to undefined concepts
      Fail: Random ordering of topics

□ 20. Terminology is consistent
      Verify: Same concept uses same term throughout
      Verify: Abbreviations defined at first use
      Fail: "Component" in one section, "widget" in another
      for the same concept

□ 21. No filler or unnecessary content
      Verify: Every section serves a purpose
      Verify: No marketing language or unnecessary preamble
      Verify: Cutting any paragraph would lose information
      Fail: Paragraphs that repeat what was already said

□ 22. Diagrams/tables used where appropriate
      Verify: Complex relationships shown visually
      Verify: Comparisons in table format
      Verify: Architecture in diagram format
      Fail: Long prose where a table would be clearer

□ 23. ASCII diagrams render correctly
      Verify: View in fixed-width font
      Verify: Box-drawing characters aligned
      Verify: Diagrams under 70 characters wide

□ 24. No broken formatting
      Verify: All code blocks properly closed
      Verify: All lists properly indented
      Verify: No raw HTML
      Verify: No orphaned markdown syntax (unclosed **)

□ 25. No placeholder or TODO content
      Verify: No "TBD", "TODO", "FIXME" in published content
      Verify: No "Lorem ipsum" or placeholder text
      Verify: No "[insert example here]" gaps

□ 26. External references are valuable
      Verify: Links to official docs, not random blog posts
      Verify: Links work (not 404)
      Verify: Links are relevant (not just padding)

□ 27. Performance guidance included (where applicable)
      Verify: If the skill involves code, performance is addressed
      Verify: Quantitative guidance preferred ("< 200ms" not "fast")
      N/A if the skill is purely conceptual

□ 28. Security considerations included (where applicable)
      Verify: Security implications of the approach are noted
      Verify: Common security mistakes are warned against
      N/A if no security relevance

□ 29. Testing guidance included (where applicable)
      Verify: How to verify the skill was applied correctly
      Verify: What to test, not just "write tests"
      N/A if the skill is about concepts/planning

□ 30. Accessibility and inclusivity considered
      Verify: If UI-related, accessibility is addressed
      Verify: Examples don't use culturally biased assumptions
      N/A if the skill has no user-facing component

Agent Compatibility (5 points)

□ 31. Instructions are unambiguous
      Test: Give the skill to an AI agent with only the skill as context
      Verify: Agent interprets instructions as intended
      Fail: Agent takes a different action than expected

□ 32. Decision criteria are explicit
      Verify: Any "choose between A or B" includes selection criteria
      Verify: No "use appropriate" without defining appropriate
      Fail: Agent must guess which option to choose

□ 33. Scope boundaries are clear
      Verify: "When to Apply" and "When NOT to Apply" specified
      Verify: Agent can determine skill relevance to a task
      Fail: Agent applies skill in wrong context

□ 34. Token-efficient
      Verify: No unnecessary repetition
      Verify: Lists and tables preferred over verbose prose
      Verify: Under 3000 tokens for core content
      Fail: Same information repeated in different sections

□ 35. Standalone usable
      Verify: Skill works without loading other skills first
      Verify: Enough context included for independent use
      Fail: Following instructions requires reading another skill

Scoring

Scoring Guide:
├── Each criterion: Pass (1 point) or Fail (0 points)
├── Some criteria marked N/A (don't count toward total)
├── Total possible: 35 (minus any N/A)
├── Calculate: Score / Applicable Criteria * 100 = Quality %

Quality Tiers:
├── 90-100%: Excellent — Ready to publish as featured skill
├── 80-89%:  Good — Ready to publish, minor improvements optional
├── 70-79%:  Adequate — Publishable with known limitations
├── 60-69%:  Needs Work — Fix issues before publishing
├── Below 60%: Draft — Significant revision needed

Quick Review (5-Minute Check)

If you only have 5 minutes, check these critical items:

□ Frontmatter is valid and complete
□ Purpose section exists and is clear
□ At least one code example runs correctly
□ "When to Apply" section exists
□ No TODO/placeholder content
□ Instructions are specific (not vague)
□ File is between 100-600 lines

If all pass: Skill is minimally viable.
If any fail: Fix before publishing.

Automated Checks

Automate these checks in a CI pipeline or pre-publish script:

Automatable (script can verify):
├── Frontmatter structure and required fields
├── Heading hierarchy
├── Code block language specifiers
├── File length
├── No TODO/FIXME/TBD markers
├── No orphaned markdown syntax
├── Version format (semver)
├── Tag count (3-8)
├── External link validity (HTTP check)
└── Category matches directory name

Requires Human Review:
├── Content accuracy
├── Code correctness
├── Instruction clarity
├── Example quality
├── Logical progression
├── Security considerations
└── Agent compatibility

When to Apply This Skill

Use this skill when:

• Reviewing a skill file before publishing
• Establishing quality standards for a team
• Auditing an existing skill pack for quality
• Training new skill authors on expectations
• Deciding whether a skill needs revision
• Creating automated skill validation pipelines