gardening-skills-wiki
Maintain skills wiki health - check links, naming, cross-references, and coverage
When & Why to Use This Skill
The Gardening Skills Wiki is a specialized automation toolkit designed to maintain the structural integrity and health of Claude agent skill repositories. It prevents documentation rot by automating link validation, enforcing strict naming conventions, and ensuring comprehensive index coverage, making it an essential utility for developers managing large-scale AI skill libraries.
Use Cases
- Automated Link Validation: Detects and repairs broken internal references, relative path errors, and incorrectly formatted links to ensure seamless navigation.
- Metadata & Naming Enforcement: Automatically audits directory structures for kebab-case consistency and verifies that all skills contain required frontmatter like versioning and descriptions.
- Orphaned Skill Detection: Identifies skills that are missing from INDEX files, ensuring every tool in the repository is discoverable and properly categorized.
- Maintenance Workflow Integration: Provides a master 'garden.sh' script for periodic health checks or pre-commit hooks to keep the knowledge base clean during active development.
| name | Gardening Skills Wiki |
|---|---|
| description | Maintain skills wiki health - check links, naming, cross-references, and coverage |
| when_to_use | When adding/removing skills. When reorganizing categories. When links feel broken. Periodically (weekly/monthly) to maintain wiki health. When INDEX files don't match directory structure. When cross-references might be stale. |
| version | 1.0.0 |
| languages | bash |
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 namedescription: One-line summarywhen_to_use: Symptoms and situations (CSO-critical)version: Semantic version
Optional fields:
languages: Applicable languagesdependencies: Required toolscontext: 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/orskills/gardening-skills-wiki/~/) - should beskills/ @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.