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

@

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

check-links.sh

@

check-links.sh

skills/

check-links.sh

@

check-links.sh

check-naming.sh

check-naming.sh

rm -rf

check-index-coverage.sh

check-index-coverage.sh

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

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

Maintained wiki = findable skills = reusable knowledge.