dev-skills

Appearance

Skills Library Maintenance ​

Validate and fix issues in the skills library.

Target ​

Goal: Skills library passes all validation checks

Acceptance Criteria ​

Skill Files:

  • [ ] All SKILL.md files have frontmatter with name and description
  • [ ] Each skill's name matches its directory name
  • [ ] Each skill's description is a single line, ≤200 characters
  • [ ] SKILL.md H1 heading matches the skill purpose

Index Completeness:

  • [ ] All skill directories are listed in skills/index.md
  • [ ] All entries in index point to existing skills
  • [ ] No orphaned skill directories

Index Quality:

  • [ ] Index organized by category with clear headings
  • [ ] All skill links use correct relative paths
  • [ ] No duplicate entries

Homepage Features:

  • [ ] Every skill directory has a feature card in index.md frontmatter
  • [ ] Every feature card links to an existing skill directory
  • [ ] Feature cards are grouped by category (Agents, JavaScript, Node.js, Web, Frameworks, Git & GitHub, Quality, DevOps & Infrastructure, Meta)
  • [ ] Feature titles and details match their SKILL.md metadata
  • [ ] No orphaned or duplicate feature cards

Current State ​

Check the current state before making changes:

sh
# List all skills
ls -d skills/*/

# Check for SKILL.md in each
for d in skills/*/; do
  if [ ! -f "$d/SKILL.md" ]; then
    echo "Missing SKILL.md: $d"
  fi
done

Convergence Loop ​

  1. Validate — Scan all skill directories, check acceptance criteria
  2. Report — Show validation table (pass/fail per criterion)
  3. Fix — Launch parallel fixes for each issue type
  4. Re-validate — Check fixes worked
  5. Repeat — Until all criteria pass or 3 iterations reached

Validation Checks ​

Frontmatter ​

Every SKILL.md must have YAML frontmatter with name and description fields. The name must exactly match the skill's directory name. The description must be a single line and must not exceed 200 characters.

Index Coverage ​

Every skill directory must be listed in skills/index.md. Every entry in the index must point to an existing skill. No orphaned directories.

Index Quality ​

Index organized by topic with clear headings, correct relative paths, and no duplicate entries.

Homepage Features ​

Every skill directory must have a corresponding feature card in the features array in index.md frontmatter. Each card must have icon, title, details, and link fields. The link must point to an existing skill directory. Cards are grouped by category using YAML comments (e.g., # Agents, # JavaScript). Titles and details should reflect the skill's SKILL.md metadata.

Reference ​

Skill directory structure:

skills/
  skill-name/
    SKILL.md         # Required
    reference.md     # Optional

Frontmatter format:

yaml
---
name: skill-name
description: When to use this skill.
metadata:
  title: Human-Readable Title
---