xqt2023-ux/Gardening Skills Wiki

Gardening Skills Wiki

Overview

The skills wiki needs regular maintenance to stay healthy: links break, skills get orphaned, naming drifts, INDEX files fall out of sync.

Core principle: Automate health checks to maintain wiki quality without burning tokens on manual inspection.

When to Use

Run gardening after:

• Adding new skills
• Removing or renaming skills
• Reorganizing categories
• Updating cross-references
• Suspicious that links are broken

Periodic maintenance:

• Weekly during active development
• Monthly during stable periods

Quick Health Check

# Run all checks
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# Or run specific checks
~/.claude/skills/meta/gardening-skills-wiki/check-links.sh
~/.claude/skills/meta/gardening-skills-wiki/check-naming.sh
~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh

# Analyze search gaps (what skills are missing)
~/.claude/skills/meta/gardening-skills-wiki/analyze-search-gaps.sh

The master script runs all checks and provides a health report.

What Gets Checked

1. Link Validation (check-links.sh)

Checks:

• Backtick-wrapped @ links - backticks disable resolution
• Relative paths like skills/ or skills/gardening-skills-wiki/~/ - should use skills/ absolute paths
• All skills/ references resolve to existing files
• Skills referenced in INDEX files exist
• Orphaned skills (not in any INDEX)

Fixes:

• Remove backticks from @ references
• Convert skills/ and skills/gardening-skills-wiki/~/ relative paths to skills/ absolute paths
• Update broken skills/ references to correct paths
• Add orphaned skills to their category INDEX
• Remove references to deleted skills

2. Naming Consistency (check-naming.sh)

Checks:

• Directory names are kebab-case
• No uppercase or underscores in directory names
• Frontmatter fields present (name, description, when_to_use, version, type)
• Skill names use active voice (not "How to...")
• Empty directories

Fixes:

• Rename directories to kebab-case
• Add missing frontmatter fields
• Remove empty directories
• Rephrase names to active voice

3. INDEX Coverage (check-index-coverage.sh)

Checks:

• All skills listed in their category INDEX
• All category INDEX files linked from main INDEX
• Skills have descriptions in INDEX entries

Fixes:

• Add missing skills to INDEX files
• Add category links to main INDEX
• Add descriptions for INDEX entries

Common Issues and Fixes

Broken Links

❌ BROKEN: skills/debugging/root-cause-tracing
   Target: /path/to/skills/debugging/root-cause-tracing/SKILL.md

Fix: Update the reference path - skill might have moved or been renamed.

Orphaned Skills

⚠️  ORPHANED: test-invariants/SKILL.md not in testing/INDEX.md

Fix: Add to the category INDEX:

- skills/gardening-skills-wiki/test-invariants - Description of skill

Backtick-Wrapped Links

❌ BACKTICKED: skills/testing/condition-based-waiting on line 31
   File: getting-started/SKILL.md
   Fix: Remove backticks - use bare @ reference

Fix: Remove backticks:

# ❌ Bad - backticks disable link resolution
`skills/testing/condition-based-waiting`

# ✅ Good - bare @ reference
skills/testing/condition-based-waiting

Relative Path Links

❌ RELATIVE: skills/testing in coding/SKILL.md
   Fix: Use skills/ absolute path instead

Fix: Convert to absolute path:

# ❌ Bad - relative paths are brittle
skills/testing/condition-based-waiting

# ✅ Good - absolute skills/ path
skills/testing/condition-based-waiting

Naming Issues

⚠️  Mixed case: TestingPatterns (should be kebab-case)

Fix: Rename directory:

cd ~/.claude/skills/testing
mv TestingPatterns testing-patterns
# Update all references to old name

Missing from INDEX

❌ NOT INDEXED: condition-based-waiting/SKILL.md

Fix: Add to testing/INDEX.md:

## Available Skills

- skills/gardening-skills-wiki/condition-based-waiting - Replace timeouts with condition polling

Empty Directories

⚠️  EMPTY: event-based-testing

Fix: Remove if no longer needed:

rm -rf ~/.claude/skills/event-based-testing

Naming Conventions

Directory Names

• Format: kebab-case (lowercase with hyphens)
• Process skills: Use gerunds when appropriate (creating-skills, testing-skills)
• Pattern skills: Use core concept (flatten-with-flags, test-invariants)
• Avoid: Mixed case, underscores, passive voice starters ("how-to-")

Frontmatter Requirements

Required fields:

• name: Human-readable name
• description: One-line summary
• when_to_use: Symptoms and situations (CSO-critical)
• version: Semantic version

Optional fields:

• languages: Applicable languages
• dependencies: Required tools
• context: Special context (e.g., "AI-assisted development")

Automation Workflow

After Adding New Skill

# 1. Create skill
mkdir -p ~/.claude/skills/category/new-skill
vim ~/.claude/skills/category/new-skill/SKILL.md

# 2. Add to category INDEX
vim ~/.claude/skills/category/INDEX.md

# 3. Run health check
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# 4. Fix any issues reported

After Reorganizing

# 1. Move/rename skills
mv ~/.claude/skills/old-category/skill ~/.claude/skills/new-category/

# 2. Update all references (grep for old paths)
grep -r "skills/gardening-skills-wiki/old-category/skill" ~/.claude/skills/

# 3. Run health check
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# 4. Fix broken links

Periodic Maintenance

# Monthly: Run full health check
~/.claude/skills/meta/gardening-skills-wiki/garden.sh

# Review and fix:
# - ❌ errors (broken links, missing skills)
# - ⚠️  warnings (naming, empty dirs)

The Scripts

garden.sh (Master)

Runs all health checks and provides comprehensive report.

Usage:

~/.claude/skills/meta/gardening-skills-wiki/garden.sh [skills_dir]

check-links.sh

Validates all @ references and cross-links.

Checks:

• Backtick-wrapped @ links (disables resolution)
• Relative paths (skills/ or skills/gardening-skills-wiki/~/) - should be skills/
• @ reference resolution to existing files
• Skills in INDEX files exist
• Orphaned skills detection

check-naming.sh

Validates naming conventions and frontmatter.

Checks:

• Directory name format
• Frontmatter completeness
• Empty directories

check-index-coverage.sh

Validates INDEX completeness.

Checks:

• Skills listed in category INDEX
• Categories linked in main INDEX
• Descriptions present

Quick Reference

| Issue | Script | Fix | |-------|--------|-----| | Backtick-wrapped links | check-links.sh | Remove backticks from @ refs | | Relative paths | check-links.sh | Convert to skills/ absolute | | Broken links | check-links.sh | Update @ references | | Orphaned skills | check-links.sh | Add to INDEX | | Naming issues | check-naming.sh | Rename directories | | Empty dirs | check-naming.sh | Remove with rm -rf | | Missing from INDEX | check-index-coverage.sh | Add to INDEX.md | | No description | check-index-coverage.sh | Add to INDEX entry |

Output Symbols

• ✅ Pass - Item is correct
• ❌ Error - Must fix (broken link, missing skill)
• ⚠️ Warning - Should fix (naming, empty dir)
• ℹ️ Info - Informational (no action needed)

Integration with Workflow

Before committing skill changes:

~/.claude/skills/meta/gardening-skills-wiki/garden.sh
# Fix all ❌ errors
# Consider fixing ⚠️  warnings
git add .
git commit -m "Add/update skills"

When links feel suspicious:

~/.claude/skills/meta/gardening-skills-wiki/check-links.sh

When INDEX seems incomplete:

~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh

Common Rationalizations

| Excuse | Reality | |--------|---------| | "Will check links manually" | Automated check is faster and more thorough | | "INDEX probably fine" | Orphaned skills happen - always verify | | "Naming doesn't matter" | Consistency aids discovery and maintenance | | "Empty dir harmless" | Clutter confuses future maintainers | | "Can skip periodic checks" | Issues compound - regular maintenance prevents big cleanups |

Real-World Impact

Without gardening:

• Broken links discovered during urgent tasks
• Orphaned skills never found
• Naming drifts over time
• INDEX files fall out of sync

With gardening:

• 30-second health check catches issues early
• Automated validation prevents manual inspection
• Consistent structure aids discovery
• Wiki stays maintainable

The Bottom Line

Don't manually inspect - automate the checks.

Run garden.sh after changes and periodically. Fix ❌ errors immediately, address ⚠️ warnings when convenient.

Maintained wiki = findable skills = reusable knowledge.