skill-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Review & Gardening

Skill审核与Skill Gardening

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

用于维护51个以上joelclaw skill准确性与健康状态的自动化及手动流程。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.

权威数据源：
```
~/Code/joelhooks/joelclaw/skills/
```
（代码仓库，完全由git追踪）

主目录使用端（从仓库创建符号链接）：

~/.agents/skills/<name>

→

~/Code/joelhooks/joelclaw/skills/<name>

~/.pi/agent/skills/<name>

→

~/Code/joelhooks/joelclaw/skills/<name>

绝对不要将skill内容放在点目录（
```
.agents/
```
、
```
.pi/
```
、
```
.claude/
```
）中。这些目录仅用于存放符号链接。
第三方skill包（axiom-*、marketing等）作为外部安装包存放在
```
~/.agents/skills/
```
中——不要放入仓库。

Automated Garden (Inngest)

自动化Skill Gardening（Inngest）

The

skill-garden

function runs daily at 6am PT and checks:

skill-garden

函数每天太平洋时间早上6点运行，检查以下内容：

Daily (structural + patterns)

每日检查（结构+模式）

Broken symlinks — dead links in
```
~/.agents/skills/
```
,
```
~/.pi/agent/skills/
```
Non-canonical REAL DIRs — directories in home skill dirs that should be symlinks
Missing frontmatter — skills without SKILL.md or required frontmatter (name, description)
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
```
Orphans — skills in repo with no symlink from any home dir

损坏的符号链接 —
```
~/.agents/skills/
```
、
```
~/.pi/agent/skills/
```
中的无效链接
非标准真实目录 — 主目录skill文件夹中本应是符号链接的实际目录
缺少前置元数据 — 没有SKILL.md或缺少必要前置元数据（名称、描述）的skill
过时模式 — 引用已停用基础设施的skill：
- 旧版轻量k8s发行版术语 → 已替换为Colima上的Talos
- 旧版向量数据库术语 → 已替换为支持向量搜索的Typesense
- 针对worker标签的launchctl命令 → Worker现在运行在k8s中
- 独立Worker克隆路径 → 已替换为单体仓库中的
```
packages/system-bus/
```
- 独立CLI仓库路径/别名 → CLI现在位于单体仓库的
```
packages/cli/
```
  ，命令为
```
joelclaw
```
孤立skill — 仓库中存在但未在任何主目录创建符号链接的skill

Monthly (1st of month, LLM deep review)

月度检查（每月1日，LLM深度审核）

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

读取当前
```
AGENTS.md
```
作为基准事实
通过
```
pi
```
推理将每个skill的内容与系统实际情况进行对比
标记过时的工作流、错误的版本、缺失的功能
生成结构化报告

Triggers

触发方式

bash

undefined

bash

undefined

On-demand via event

通过事件按需触发

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

joelclaw send "skill-garden/check" joelclaw send "skill-garden/check" --data '{"deep": true}' # 强制触发LLM审核

Daily cron: 0 6 * * * (automatic)

每日定时任务：0 6 * * *（自动运行）

undefined

undefined

Output

输出结果

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

OTEL事件：
```
skill-garden.findings
```
发现问题时发送网关通知（无问题时无打扰）
按问题类型分类的结构化JSON报告

Manual Review Process

手动审核流程

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

当自动化Skill Gardening标记问题，或进行定期深度审核时：

1. Run the audit

1. 运行审计

bash

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

bash

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

2. Check for structural issues

2. 检查结构问题

bash

undefined

bash

undefined

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)

查找孤立skill（仓库中存在但主目录无符号链接）

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

undefined

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

undefined

3. Fix structural issues

3. 修复结构问题

bash

undefined

bash

undefined

Fix a broken symlink

修复损坏的符号链接

rm ~/.agents/skills/<name> ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.agents/skills/<name>

Convert a REAL DIR to symlink

将真实目录转换为符号链接

rm -rf ~/.pi/agent/skills/<name> ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.pi/agent/skills/<name>

Add missing home dir symlink

添加缺失的主目录符号链接

ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.agents/skills/<name> ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.pi/agent/skills/<name>

undefined

ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.agents/skills/<name> ln -s ~/Code/joelhooks/joelclaw/skills/<name> ~/.pi/agent/skills/<name>

undefined

4. Fix stale content

4. 修复过时内容

When a skill references outdated architecture:

Read the skill:
```
cat skills/<name>/SKILL.md
```
Cross-reference with
```
AGENTS.md
```
and current system state
Update the skill with current facts

Commit:

git add skills/<name> && git commit -m "skill(<name>): update for current architecture"

当skill引用过时的架构时：

查看skill内容：
```
cat skills/<name>/SKILL.md
```
对照
```
AGENTS.md
```
和当前系统状态进行交叉验证
根据当前实际情况更新skill内容

提交修改：

git add skills/<name> && git commit -m "skill(<name>): update for current architecture"

5. Adding a new skill

5. 添加新skill

bash

mkdir -p skills/<name>

bash

mkdir -p skills/<name>

Write SKILL.md with frontmatter: name, description, version, author, tags

编写包含前置元数据的SKILL.md：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](../add-skill/SKILL.md) for the full idiomatic process.


完整的标准流程请参考[add-skill skill](../add-skill/SKILL.md)。

Stale Pattern Registry

过时模式注册表

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

Pattern	What it means	Current reality
legacy k8s distro token	Old k8s distribution reference	Talos v1.12.4 on Colima
legacy vector DB token	Old vector store reference	Typesense with vector search
launchctl worker command token	Old worker deploy mode	k8s Deployment
standalone worker clone path token	Old worker path	`packages/system-bus/` in monorepo
standalone CLI path token	Old CLI path	`packages/cli/` in monorepo
short CLI alias token	Old CLI name	`joelclaw` CLI

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

随着基础设施变更，请更新此列表。Inngest函数会读取这些模式。

模式	含义	当前实际情况
legacy k8s distro token	旧版k8s发行版引用	Colima上的Talos v1.12.4
legacy vector DB token	旧版向量存储引用	支持向量搜索的Typesense
launchctl worker command token	旧版Worker部署模式	k8s Deployment
standalone worker clone path token	旧版Worker路径	单体仓库中的 `packages/system-bus/`
standalone CLI path token	旧版CLI路径	单体仓库中的 `packages/cli/`
short CLI alias token	旧版CLI名称	`joelclaw` CLI

当基础设施变更时，请更新此表格以及
skill-garden.ts
中
STALE_PATTERNS
内的精确正则表达式列表。

Required Frontmatter

必备前置元数据

Every skill MUST have:

yaml

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

Recommended additional fields:

yaml

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

每个skill都必须包含：

yaml

---
name: skill-name
description: "该skill的功能及适用场景"
---

推荐添加的额外字段：

yaml

version: 1.0.0
author: Joel Hooks
tags: [relevant, tags]
displayName: 可读名称

Key Paths

关键路径

What	Path
Repo skills (canonical)	`~/Code/joelhooks/joelclaw/skills/`
Inngest function	`packages/system-bus/src/inngest/functions/skill-garden.ts`
ADR	`~/Vault/docs/decisions/0179-automated-skill-gardening.md`
Home dir: agents	`~/.agents/skills/`
Home dir: pi	`~/.pi/agent/skills/`
Stale patterns	`STALE_PATTERNS` in `skill-garden.ts`

内容	路径
仓库skill（权威数据源）	`~/Code/joelhooks/joelclaw/skills/`
Inngest函数	`packages/system-bus/src/inngest/functions/skill-garden.ts`
ADR文档	`~/Vault/docs/decisions/0179-automated-skill-gardening.md`
主目录：agents	`~/.agents/skills/`
主目录：pi	`~/.pi/agent/skills/`
过时模式	`skill-garden.ts` 中的 `STALE_PATTERNS`