用途:对用户的智能体配置进行评分。它读取最近的本地智能体会话记录,按效率、代码质量、流程合规和冗长度四个维度打分,然后提出具体的技能修改建议,并渲染一个可分享的报告页面。报告可覆盖当前仓库、选定项目或全部本地会话,也可只评估项目技能或同时评估项目与全局技能。
主要能力:先确认执行环境是否受支持,再询问要评分的会话范围与技能范围;用 collect_sessions.py 收集会话与技能清单;对每条会话按四份评分标准(efficiency、code-quality、procedure-compliance、verbosity)打分;聚合出效率、代码质量、流程合规、冗长度、技能覆盖率与加权总分;从失败会话中提炼 top_findings 与 suggestions;按 skill-improvements.md 起草技能改进,生成统一 diff;最后用 render_report.py 输出单个自包含 report.html,并尝试在浏览器打开。报告页含评分卡、发现与建议,长 diff 可折叠,并有“share as png”按钮在本地导出 1200x675 分享图。
使用方式:以 SKILL_ROOT 为包含 SKILL.md 的目录。先运行 git rev-parse --show-toplevel 判断是否在 git 仓库内,再按提示选择会话范围与技能范围。创建临时目录:REPORT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/skill-doctor-XXXXXXXX")"。收集命令示例:python3 "$SKILL_ROOT/scripts/collect_sessions.py" --out "$REPORT_DIR" <conversation-scope arguments> <skill-scope arguments>。常用参数包括 --harness、--repo、--all-conversations、--include-global-skills、--days(默认 45)、--max-sessions(默认 12)、--skills-dir、--include-subagents。若 inventory.json 中 sessions_sampled 为 0 则停止并提示;skills_found 为 0 时继续,报告转为创建技能的依据。评分时读取 $REPORT_DIR/transcripts/ 下每条记录,对照四份评分标准给出标签、分数与理由;代码质量仅在出现代码变更时评分,否则记 insufficient_evidence 并排除。聚合时用 curve(score)=0.5+0.5score 转换,overall=0.25efficiency+0.25code_quality+0.2procedure_compliance+0.15verbosity+0.15skill_coverage。失败会话定义为至少一项适用分数低于 0.5,仅用失败会话作为改进建议依据。随后写 report.json 并运行:python3 "$SKILL_ROOT/scripts/render_report.py" "$REPORT_DIR/report.json" --open。
适用场景:想了解自己智能体技能配置表现、找出低效或不合规会话、并据此改进项目技能或新建技能时。
限制:全部在本地运行,绝不上传会话记录、会话文件或其任何片段,唯一可分享产物是用户主动发布的报告;不把产物写入用户仓库,每次运行使用独立临时目录;本步骤不修改用户真实技能文件;评分依赖受支持的执行环境,若不受支持或无法确认则按参考文档停止行为处理,不创建报告目录也不读取会话历史。具体支持的执行环境、来源标识与存储细节需查阅 references/supported-harnesses.md,资料未提供其内容。