⚡

技能文档修复工具Skill core-fix-skill-docs

技能文档修复工具是一个用于自动检查和修复Claude技能系统中缺失文档文件的维护工具。该工具能够扫描技能目录，检测SKILL.md文件中引用的参考文档是否存在缺失，并自动从docs.rs等在线文档源获取缺失内容。支持代理模式和内联模式两种运行方式，具备智能错误处理和多种修复选项，包括仅检查、自动修复和删除无效引用等功能。关键词：技能文档修复、Claude技能维护、自动化文档管理、缺失文件检测、docs.rs文档获取、技能系统工具、开发工具自动化

DevOps 0 次安装 0 次浏览 更新于 2/27/2026

name: core-fix-skill-docs

内部维护工具 - 无描述以防止自动触发

触发方式: /fix-skill-docs 命令

argument-hint: “[crate_name] [–check-only]” context: fork agent: general-purpose

修复技能文档

版本: 2.1.0 | 最后更新: 2025-01-27

检查和修复动态技能中缺失的参考文件。

使用方法

/fix-skill-docs [crate_name] [--check-only] [--remove-invalid]

参数:

  • crate_name: 指定要检查的crate（可选，默认为全部）
  • --check-only: 仅报告问题，不修复
  • --remove-invalid: 删除无效引用而不是创建文件

执行模式检测

关键：检查代理基础设施是否可用。

此技能可在两种模式下运行：

  • 代理模式：使用后台代理获取文档
  • 内联模式：直接使用agent-browser CLI或WebFetch执行

代理模式（插件安装）

当代理基础设施可用时，使用后台代理进行获取：

操作说明

1. 扫描技能目录

# 如果提供了crate_name
skill_dir=~/.claude/skills/{crate_name}

# 否则扫描所有
for dir in ~/.claude/skills/*/; do
    # 处理每个技能
done

2. 解析SKILL.md中的引用

从文档部分提取引用的文件：

## 文档
- `./references/file1.md` - 描述

3. 检查文件是否存在

if [ ! -f "{skill_dir}/references/{filename}" ]; then
    echo "缺失: {filename}"
fi

4. 报告状态

=== {crate_name} ===
SKILL.md: 正常
references/:
  - sync.md: 正常
  - runtime.md: 缺失

需要操作: 1个文件缺失

5. 修复缺失文件（代理模式）

启动后台代理获取文档：

Task(
  subagent_type: "general-purpose",
  run_in_background: true,
  prompt: "从docs.rs获取{crate_name}/{module}的文档。
           使用agent-browser CLI导航到https://docs.rs/{crate_name}/latest/{crate_name}/{module}/
           提取主要文档内容并保存到~/.claude/skills/{crate_name}/references/{module}.md"
)

内联模式（仅技能安装）

当代理基础设施不可用时，直接执行：

步骤1：扫描技能目录

# 列出所有技能
ls ~/.claude/skills/

# 或检查特定技能
ls ~/.claude/skills/{crate_name}/

步骤2：解析SKILL.md中的引用

读取SKILL.md并提取所有./references/*.md模式：

# 使用Read工具
Read("~/.claude/skills/{crate_name}/SKILL.md")

# 查找类似行：
# - `./references/sync.md` - 同步原语
# - `./references/runtime.md` - 运行时配置

步骤3：检查文件是否存在

# 检查每个引用的文件
for ref in references; do
  if [ ! -f "~/.claude/skills/{crate_name}/references/${ref}.md" ]; then
    echo "缺失: ${ref}.md"
  fi
done

步骤4：报告状态

输出格式：

=== {crate_name} ===
SKILL.md: 正常
references/:
  - sync.md: 正常
  - runtime.md: 缺失

需要操作: 1个文件缺失

步骤5：修复缺失文件（内联）

对于每个缺失的文件：

使用agent-browser CLI：

agent-browser open "https://docs.rs/{crate_name}/latest/{crate_name}/{module}/"
agent-browser get text ".docblock"
# 保存输出到~/.claude/skills/{crate_name}/references/{module}.md
agent-browser close

使用WebFetch备用方案：

WebFetch("https://docs.rs/{crate_name}/latest/{crate_name}/{module}/",
         "提取此模块的主要文档内容")

然后写入内容：

Write("~/.claude/skills/{crate_name}/references/{module}.md", <fetched_content>)

步骤6：更新SKILL.md（如果使用–remove-invalid）

如果设置了--remove-invalid标志且无法获取文件：

# 读取当前SKILL.md
Read("~/.claude/skills/{crate_name}/SKILL.md")

# 删除无效引用行
Edit("~/.claude/skills/{crate_name}/SKILL.md",
     old_string="- `./references/{invalid_file}.md` - 描述",
     new_string="")

工具优先级

  1. agent-browser CLI - 获取文档的主要工具
  2. WebFetch - 如果agent-browser不可用时的备用方案
  3. 编辑SKILL.md - 用于删除无效引用（仅–remove-invalid）

示例

检查所有技能（–check-only）

/fix-skill-docs --check-only

# 输出：
=== tokio ===
SKILL.md: 正常
references/:
  - sync.md: 正常
  - runtime.md: 缺失
  - task.md: 正常

=== serde ===
SKILL.md: 正常
references/:
  - derive.md: 正常

摘要: 1个技能中1个文件缺失

修复特定Crate

/fix-skill-docs tokio

# 从docs.rs获取缺失的runtime.md
# 报告成功

删除无效引用

/fix-skill-docs tokio --remove-invalid

# 如果无法获取runtime.md：
# 从SKILL.md中删除引用

错误处理

错误 原因 解决方案
代理不可用 仅技能安装 使用内联模式
技能目录为空 未安装任何技能 先运行/sync-crate-skills
docs.rs不可用 网络问题 重试或使用–remove-invalid
权限被拒绝 目录问题 检查~/.claude/skills/权限
SKILL.md格式无效 技能损坏 重新生成技能