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

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