Skill Review & Gardening

Automated and manual processes for keeping the 51+ joelclaw skills accurate and healthy. ADR-0179.

Canonical Contract

• Source of truth: ~/Code/joelhooks/joelclaw/skills/ (repo, fully git-tracked)
• Home dir consumers (symlink IN to repo):
  • ~/.agents/skills/<name> → ~/Code/joelhooks/joelclaw/skills/<name>
  • ~/.pi/agent/skills/<name> → ~/Code/joelhooks/joelclaw/skills/<name>
• Never put skill content in dot directories (.agents/, .pi/, .claude/). Those are symlink consumers.
• Third-party skill packs (axiom-*, marketing, etc.) live in ~/.agents/skills/ as external installs — NOT in the repo.

Automated Garden (Inngest)

The skill-garden function runs daily at 6am PT and checks:

Daily (structural + patterns)

1. Broken symlinks — dead links in ~/.agents/skills/, ~/.pi/agent/skills/
2. Non-canonical REAL DIRs — directories in home skill dirs that should be symlinks
3. Missing frontmatter — skills without SKILL.md or required frontmatter (name, description)
4. Stale patterns — skills referencing known-dead infrastructure:
   • legacy lightweight-k8s distro terms → replaced by Talos on Colima
   • retired vector DB terms → replaced by Typesense vector search
   • launchctl commands targeting worker labels → worker runs in k8s
   • old standalone worker clone paths → monorepo packages/system-bus/
   • old standalone CLI repo paths/aliases → CLI is packages/cli/ + joelclaw
5. Orphans — skills in repo with no symlink from any home dir

Monthly (1st of month, LLM deep review)

• Reads current AGENTS.md as ground truth
• Compares each skill's content against system reality via pi inference
• Flags outdated workflows, wrong versions, missing capabilities
• Produces structured report

Triggers

# On-demand via event
joelclaw send "skill-garden/check"
joelclaw send "skill-garden/check" --data '{"deep": true}'  # force LLM review

# Daily cron: 0 6 * * * (automatic)

Output

• OTEL event: skill-garden.findings
• Gateway notification when issues found (zero noise on clean days)
• Structured JSON report with findings by type

Manual Review Process

When the automated garden flags issues, or for periodic deep review:

1. Run the audit

joelclaw send "skill-garden/check" --data '{"deep": true}'

2. Check for structural issues

# Broken symlinks
find ~/.agents/skills/ ~/.pi/agent/skills/ -maxdepth 1 -type l ! -exec test -e {} \; -print

# REAL DIRs that should be symlinks
for dir in ~/.agents/skills ~/.pi/agent/skills; do
  find "$dir" -maxdepth 1 -type d ! -type l | while read d; do
    name=$(basename "$d")
    [ -d ~/Code/joelhooks/joelclaw/skills/"$name" ] && echo "NON-CANONICAL: $d"
  done
done

# Orphan skills (in repo, no home dir symlink)
for skill in ~/Code/joelhooks/joelclaw/skills/*/; do
  name=$(basename "$skill")
  [ ! -L ~/.agents/skills/"$name" ] && [ ! -L ~/.pi/agent/skills/"$name" ] && echo "ORPHAN: $name"
done

3. Fix structural issues

# Canonical repair path for repo-local skills
joelclaw skills ensure <name>

# Or explicitly from another repo root
joelclaw skills ensure <name> --source-root /abs/repo

If joelclaw skills ensure fails because a consumer target is a real file/dir instead of a symlink, fix that conflict manually, then rerun the command.

4. Fix stale content

When a skill references outdated architecture:

1. Read the skill: read skills/<name>/SKILL.md
2. Cross-reference with AGENTS.md and current system state
3. Update the skill with current facts
4. Commit: git add skills/<name> && git commit -m "skill(<name>): update for current architecture"

5. Adding a new skill

mkdir -p skills/<name>
# Write SKILL.md with frontmatter: name, description, version, author, tags
# Symlink from home dirs:
ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.agents/skills/<name>
ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.pi/agent/skills/<name>
git add skills/<name>
git commit -m "skill(<name>): add new skill"

See the add-skill skill for the full idiomatic process.

Stale Pattern Registry

Keep this list updated as infrastructure changes. The Inngest function reads these patterns.

When infrastructure changes, update this table AND the exact regex list in STALE_PATTERNS inside skill-garden.ts.

Required Frontmatter

Every skill MUST have:

---
name: skill-name
description: "What this skill does and when to use it"
---

Recommended additional fields:

version: 1.0.0
author: Joel Hooks
tags: [relevant, tags]
displayName: Human Readable Name

Key Paths