Gardening Skills Wiki

园艺技能 Wiki

概述

技能 Wiki 需要定期维护，才能保持健康：链接会失效，技能会变成孤立项，命名会逐渐不一致，INDEX 文件也会失去同步。

核心原则： 自动执行健康检查，以维护 Wiki 质量，避免将 token 浪费在手动检查上。

何时使用

在以下情况后运行园艺检查：

• 添加新技能
• 移除或重命名技能
• 重新组织类别
• 更新交叉引用
• 怀疑链接已失效

定期维护：

• 开发活跃期间每周一次
• 稳定期间每月一次

快速健康检查

# 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

主脚本会运行所有检查并生成健康报告。

检查内容

1. 链接验证（check-links.sh）

检查：

• 用反引号括起来的 @ 链接——反引号会禁用解析
• skills/ 或 skills/gardening-skills-wiki/~/ 等相对路径——应使用 skills/ 绝对路径
• 所有 skills/ 引用都能解析到现有文件
• INDEX 文件中引用的技能都存在
• 孤立技能（未列入任何 INDEX 的技能）

修复：

• 移除 @ 引用的反引号
• 将 skills/ 和 skills/gardening-skills-wiki/~/ 相对路径转换为 skills/ 绝对路径
• 将失效的 skills/ 引用更新为正确路径
• 将孤立技能添加到所属类别的 INDEX
• 移除对已删除技能的引用

2. 命名一致性（check-naming.sh）

检查：

• 目录名称是否为 kebab-case
• 目录名称中是否包含大写字母或下划线
• Frontmatter 字段是否齐全（name、description、when_to_use、version、type）
• 技能名称是否使用主动语态（而非“如何……”）
• 空目录

修复：

• 将目录重命名为 kebab-case
• 添加缺失的 frontmatter 字段
• 移除空目录
• 将名称改为主动语态

3. INDEX 覆盖情况（check-index-coverage.sh）

检查：

• 所有技能是否都列在所属类别的 INDEX 中
• 所有类别的 INDEX 文件是否都链接自主 INDEX
• INDEX 条目是否包含技能描述

修复：

• 将缺失的技能添加到 INDEX 文件
• 将类别链接添加到主 INDEX
• 为 INDEX 条目添加描述

常见问题及修复方法

失效链接

❌ BROKEN: skills/debugging/root-cause-tracing
   Target: /path/to/skills/debugging/root-cause-tracing/SKILL.md

修复： 更新引用路径——技能可能已移动或重命名。

孤立技能

⚠️  ORPHANED: test-invariants/SKILL.md not in testing/INDEX.md

修复： 添加到类别 INDEX：

- skills/gardening-skills-wiki/test-invariants - Description of skill

用反引号括起来的链接

❌ BACKTICKED: skills/testing/condition-based-waiting on line 31
   File: getting-started/SKILL.md
   Fix: Remove backticks - use bare @ reference

修复： 移除反引号：

# ❌ Bad - backticks disable link resolution
`skills/testing/condition-based-waiting`

# ✅ Good - bare @ reference
skills/testing/condition-based-waiting

相对路径链接

❌ RELATIVE: skills/testing in coding/SKILL.md
   Fix: Use skills/ absolute path instead

修复： 转换为绝对路径：

# ❌ Bad - relative paths are brittle
skills/testing/condition-based-waiting

# ✅ Good - absolute skills/ path
skills/testing/condition-based-waiting

命名问题

⚠️  Mixed case: TestingPatterns (should be kebab-case)

修复： 重命名目录：

cd ~/.claude/skills/testing
mv TestingPatterns testing-patterns
# Update all references to old name

未列入 INDEX

❌ NOT INDEXED: condition-based-waiting/SKILL.md

修复： 添加到 testing/INDEX.md：

## Available Skills

- skills/gardening-skills-wiki/condition-based-waiting - Replace timeouts with condition polling

空目录

⚠️  EMPTY: event-based-testing

修复： 如果不再需要，则移除：

rm -rf ~/.claude/skills/event-based-testing

命名规范

目录名称

• 格式： kebab-case（小写字母，以连字符分隔）
• 流程类技能： 适用时使用动名词（creating-skills、testing-skills）
• 模式类技能： 使用核心概念（flatten-with-flags、test-invariants）
• 避免： 大小写混用、下划线、以被动语态开头（“how-to-”）

Frontmatter 要求

必填字段：

• name：易读的名称
• description：单行摘要
• when_to_use：症状和适用情境（CSO 关键字段）
• version：语义化版本

可选字段：

• languages：适用语言
• dependencies：所需工具
• context：特殊情境（例如“AI 辅助开发”）

自动化工作流

添加新技能后

# 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

重新组织后

# 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

定期维护

# 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)

脚本

garden.sh（主脚本）

运行所有健康检查并生成综合报告。

用法：

~/.claude/skills/meta/gardening-skills-wiki/garden.sh [skills_dir]

check-links.sh

验证所有 @ 引用和交叉链接。

检查：

• 用反引号括起来的 @ 链接（会禁用解析）
• 相对路径（skills/ 或 skills/gardening-skills-wiki/~/）——应使用 skills/
• @ 引用是否能解析到现有文件
• INDEX 文件中的技能是否存在
• 检测孤立技能

check-naming.sh

验证命名规范和 frontmatter。

检查项：

• 目录名称格式
• Frontmatter 完整性
• 空目录

check-index-coverage.sh

验证 INDEX 的完整性。

检查项：

• 技能是否列在分类 INDEX 中
• 分类是否链接到主 INDEX
• 是否提供描述

快速参考

问题	脚本	修复方法
用反引号括起来的链接	check-links.sh	移除 @ 引用中的反引号
相对路径	check-links.sh	转换为 skills/ 绝对路径
失效链接	check-links.sh	更新 @ 引用
孤立的技能	check-links.sh	添加到 INDEX
命名问题	check-naming.sh	重命名目录
空目录	check-naming.sh	使用 rm -rf 删除
未列入 INDEX	check-index-coverage.sh	添加到 INDEX.md
没有描述	check-index-coverage.sh	添加到 INDEX 条目

输出符号

• ✅ 通过 - 项目正确
• ❌ 错误 - 必须修复（失效链接、缺少技能）
• ⚠️ 警告 - 应当修复（命名、空目录）
• ℹ️ 信息 - 仅供参考（无需操作）

与工作流集成

提交技能更改前：

~/.claude/skills/meta/gardening-skills-wiki/garden.sh
# Fix all ❌ errors
# Consider fixing ⚠️  warnings
git add .
git commit -m "Add/update skills"

发现链接似乎有问题时：

~/.claude/skills/meta/gardening-skills-wiki/check-links.sh

INDEX 似乎不完整时：

~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh

常见借口

借口	实际情况
“会手动检查链接”	自动检查更快、更全面
“INDEX 应该没问题”	技能可能会被遗漏——务必核实
“命名无关紧要”	一致性有助于发现和维护
“空目录无害”	杂乱会让未来的维护者困惑
“可以跳过定期检查”	问题会不断累积——定期维护可避免大规模清理

实际影响

不进行维护：

• 在紧急任务中才发现失效链接
• 孤立的技能永远不会被发现
• 命名随时间逐渐偏离规范
• INDEX 文件逐渐失去同步

进行维护：

• 30 秒健康检查可及早发现问题
• 自动验证免去人工检查
• 一致的结构有助于发现内容
• Wiki 始终易于维护

总结

不要手动检查——自动运行检查。

更改后以及定期运行 garden.sh。立即修复 ❌ 错误，并在方便时处理 ⚠️ 警告。

维护良好的 Wiki = 易于查找的技能 = 可复用的知识。