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

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

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.

packages/system-bus/

packages/cli/

joelclaw

When infrastructure changes, update this table AND the exact regex list in

STALE_PATTERNS

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

~/Code/joelhooks/joelclaw/skills/

packages/system-bus/src/inngest/functions/skill-garden.ts

~/Vault/docs/decisions/0179-automated-skill-gardening.md

~/.agents/skills/

~/.pi/agent/skills/

STALE_PATTERNS

skill-garden.ts