What makes hekouwang-claude-skill-doctor-skill notable?

1.6K downloads. Trust evidence available

How should hekouwang-claude-skill-doctor-skill be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

hekouwang-claude-skill-doctor-skill

会勇禾口王的AI笔记 · Agent Skill（SKILL.md）体检器。检查一个 Claude/Agent Skill 是否符合"按需加载的指令包，不是单文件巨石"的最佳实践——评 description 触发质量、SKILL.md 篇幅、渐进披露（references/ 拆分）、脚本外置、可移植性（无硬编码绝对路径）、安全（无硬编码密钥、宿主元数据与多 Skill 发现冲突），给出评分卡 + 按优先级的修复建议，并可代为重构。触发：用户说「检查我的 skill / SKILL.md 体检 / 这个 skill 规范吗 / claude-skill-doctor / audit skill / lint SKILL.md / 我的 skill 太长了 / skill 拆分 / 看看我的 skill 合不合规 / skill 对齐官方规范」。任何"评估/审查/优化某个 Agent Skill 质量或结构"的请求都应触发。

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

1.6k

Updated

Oct 10, 2026

Version

1.8.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 10, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 10, 2026
Adoption signal: 1.6K downloadsadoption · observed Oct 10, 2026
Latest release: 1.8.0release · observed Aug 30, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17639bexg8w6nymygatvtx99585dbjd:hekouwang-claude-skill-doctor-skill

Install using `clawhub skill install s17639bexg8w6nymygatvtx99585dbjd:hekouwang-claude-skill-doctor-skill` in an isolated environment before connecting it to live workloads.
No published capability contract is available yet, so validate auth and request/response behavior manually.
Review the upstream CLAWHUB listing at https://clawhub.ai/huiyonghkw/hekouwang-claude-skill-doctor-skill before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-huiyonghkw-hekouwang-claude-skill-doctor-skill/snapshot"

Documentation

CLAWHUB

149,251 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: hekouwang-claude-skill-doctor-skill
slug: hekouwang-claude-skill-doctor-skill
displayName: Claude Skill 体检器（SKILL.md Doctor）
summary: Agent Skill lint / SKILL.md doctor / skillspec audit — description 触发、渐进披露、可移植性与 OpenClaw 兼容检查。姊妹工具 md-doctor。
license: MIT-0
homepage: https://github.com/huiyonghkw/hekouwang-claude-skill-doctor-skill
version: 1.8.0
description: >
  会勇禾口王的AI笔记 · Agent Skill（SKILL.md）体检器。检查一个 Claude/Agent Skill 是否
  符合"按需加载的指令包，不是单文件巨石"的最佳实践——评 description 触发质量、SKILL.md
  篇幅、渐进披露（references/ 拆分）、脚本外置、可移植性（无硬编码绝对路径）、安全（无硬编码
  密钥、宿主元数据与多 Skill 发现冲突），给出评分卡 + 按优先级的修复建议，并可代为重构。触发：用户说「检查我的 skill /
  SKILL.md 体检 / 这个 skill 规范吗 / claude-skill-doctor / audit skill / lint SKILL.md /
  我的 skill 太长了 / skill 拆分 / 看看我的 skill 合不合规 / skill 对齐官方规范」。
  任何"评估/审查/优化某个 Agent Skill 质量或结构"的请求都应触发。
---

# hekouwang-claude-skill-doctor-skill · Agent Skill 体检器

> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`
> _不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。_

把"Agent Skill 最佳实践"做成一个能跑在任何 skill 上的检查器：机检定量 + 模型定性，
产出评分卡和可落地的修复建议。核心判据一句话——

> **SKILL.md 是模型"决定要不要加载、加载后照着做"的运行时指令包。`description` 决定它何时被唤醒；正文越精简越准；厚重细节要能"按需展开"（references/ 用到再读），而不是每次触发就把全部细节灌进上下文。**
> 一切检查项都从这句推导：这段内容值不值得在 skill 每次触发时都付一次上下文费？能不能下沉到 references/ 用到再读？

### 触发优先 + 减法优先（元判据 · 凌驾全部检查项之上）

Skill 的命脉是两条，权重最高：

1. **触发**：`description` 是模型唯一用来判断"何时唤醒本 skill"的信号。写不清"何时用"，再好的正文也永远不被加载。
2. **减法**：SKILL.md 不是图书馆。模型每代都在变强——你塞进正文的通用写法、框架教程、临时脚本，很快既过时又白占 token。**能下沉 references/ 的下沉，能外置 scripts/ 的外置，模型已经会的删掉。**

所以机检里 **#2 触发 / #3 篇幅 / #4 渐进披露 / #6 可移植 / #10 别替模型补** 权重 1.5；
"加内容"类项（#7 最小工具集、#10 配套文档）缺失只算小扣分——别一边喊"越精简越好"、一边逼作者把 skill 做臃肿。

## 品牌人设（体检报告的口吻 + 署名）

属于 **会勇禾口王的AI笔记**（定位：AI 实战拆解，硬核·具体·可复制；人设：你办公室里第一个把 AI 用明白的同事）。出体检报告时：

- **口吻**：像同事帮你看代码——直给结论、敢泼冷水（"这 description 只写了做什么、不写何时用，等于永远不被触发"），不说客套话。
- **价值化**：修复建议讲"省了什么"（每次触发少灌 100KB 冗余、别人装上不报错、该用时真能被唤醒），不堆术语。
- **署名**：报告结尾固定带 `—— 会勇禾口王的AI笔记 · @huiyonghkw`。命令行 `check.py` 的报告页脚已内置该署名。
- **去 AI 味**：定稿前避开"赋能/打造/至关重要/助力"等词，说人话。

---

## 免费 / 付费边界（重要）

- **免费（开源内核）**：`check.py` 的**文本 / JSON 报告 + 评分**。任何人本地或进 CI 随便跑。
- **免费但要自付 API 钱**：`scripts/trigger_eval.py` 触发力实测（工作流 2c）。脚本本身开源随便用，
  但它每条 query 都真调一次 `claude -p`（约 $0.09–0.15/次），**钱花在用户自己的额度上**。
  所以它是**可选叠加档、不进默认流程**——`check.py` 的零依赖卖点不受影响，不跑也能出完整体检报告。
- **付费（增值）**：**品牌可视化体检报告卡**（评分弧 + 等级带 + 明细分享图），依赖 `hekouwang-content-factory` 的私有品牌字体与版式，不随本仓库分发。
- 一句话口径：**跑检查免费，出"好看的报告图"找 @huiyonghkw。** 外部用户要图时说明是付费增值项，别用系统字体凑一张劣化图糊弄。

---

## 工作流（每次体检按这个顺序）

1. **确认目标**：用户没指明就用当前目录；说了某个 skill 就用那个 skill 目录的绝对路径（目录里要有 `SKILL.md`）。若传进来是 `~/.claude/skills/` 这种父目录，脚本会提示里面有哪些 skill，逐个体检。
2. **跑机检**（确定性层，零依赖）：
   ```bash
   python3 <此skill目录>/check.py <skill目录>
   ```
   - 需要结构化结果时加 `--json`。退出码：有 FAIL → 1，否则 0。
   - 默认 Profile 是跨宿主的 `agent`；要按 Codex `skill-creator` 的严格基础契约验收时，加
     `--profile codex`。它只允许 `name`、`description`、`license`、`allowed-tools`、`metadata`，
     并阻断不合规 name、description 尖括号和正文未完成 TODO；不适用于带 Claude/宿主扩展字段的 Skill。
   - 需要盘点一个宿主目录或仓库里的全部 Skill 时运行：
     `python3 <此skill目录>/check.py --scan <skill根目录> --json`；同样

tests/fixtures/bad/SKILL.md

---
name: BadSkill_Example
---

# Bad Skill

这是一个演示「不合格 skill」的夹具，故意踩坑：

- name 用了大写 + 下划线（应 kebab-case）。
- **缺 description**——模型无从判断何时加载本 skill（机检会判 FAIL，退出码 1）。
- 硬编码了绝对路径 /Users/someone/.claude/skills/x/assets/font.woff2（换台机器就废）。

tests/fixtures/good/SKILL.md

---
name: example-good-skill
description: >
  生成示例日报。把一段原始数据整理成一页结构化的示例日报。
  当需要演示「合格 skill 长什么样」或要一份 demo 日报时使用；
  use when you need a demo daily report.
allowed-tools:
  - Read
  - Write
---

# Example Good Skill

一个用于演示「合格 skill」的最小夹具：frontmatter 完整、description 写清了
做什么 + 何时用、正文精简、无硬编码密钥、无绝对路径。

## 何时用

当用户要一份示例日报，或想看一个达标 skill 的结构时。

## 怎么做

1. 读取用户给的原始数据。
2. 按「概览 / 明细 / 结论」三段整理。
3. 输出一页 Markdown 日报。

> 正文只放本 skill 私有的约定；通用写法交给模型自己。

README.md

# hekouwang-claude-skill-doctor-skill

> **会勇禾口王的AI笔记** 出品 · `@huiyonghkw`
> 不聊 AI 会不会取代你，只聊先用 AI 的人怎么取代你。

给 **Agent Skill（SKILL.md）** 做体检的工具。把"Skill 是按需加载的指令包、不是单文件巨石"
这条最佳实践，做成一个能跑在任何 skill 上的检查器：机检定量 + 模型定性，产出评分卡和可落地的修复建议。

## 30 秒验收

```bash
python3 check.py path/to/your-skill    # 体检任意 skill 目录
bash scripts/run-all-doctors.sh .      # 三件套（需已装 md-doctor + env-doctor）
```

姊妹工具：[`hekouwang-claude-md-doctor-skill`](https://github.com/huiyonghkw/hekouwang-claude-md-doctor-skill)（体检 AGENTS.md / CLAUDE.md）。

## 核心判据

> SKILL.md 是模型"决定要不要加载、加载后照着做"的运行时指令包。
> `description` 决定它何时被唤醒；正文越精简越准；厚重细节要能"按需展开"
> （references/ 用到再读），而不是每次触发就把全部细节灌进上下文。

## 用法

### 在 Claude Code 里（推荐）

直接用**自然语言**喊它，Claude 会自动加载本 skill、在底层跑机检、再做定性复核，给评分卡 + 按优先级的修复建议，并问要不要代为重构：

> - 「帮我体检 `~/.claude/skills/xxx` 这个 skill」
> - 「我的 SKILL.md 规范吗 / 是不是太长了 / 要不要拆 references」
> - 「audit this skill」「lint SKILL.md」

### 命令行直接跑（零依赖，仅需 Python 3）

```bash
python3 check.py <skill目录>          # 输出彩色报告
python3 check.py <skill目录> --json   # 机器可读 JSON（CI 可用）
python3 check.py <skill目录> --profile codex  # 严格校验 Codex 基础契约
```

退出码：有 FAIL → 1，否则 0（可用于 CI 卡关）。

### Codex 严格基础契约（可选）

默认 `agent` Profile 服务于 Claude/Codex/其他宿主共用的 Skill：合法的 `slug`、`version` 等宿主扩展字段不会被误伤。
如果你要按 Codex `skill-creator` 的基础规范验收一个纯 Codex Skill，附加 `--profile codex`：只允许
`name`、`description`、`license`、`allowed-tools`、`metadata`，并把不合规 kebab-case、description
中的尖括号和正文未完成的 `[TODO: ...]` 纳入 `gate`。报告 JSON 的 `profile` 字段会明确本次使用的档位。

这是一层可选的严格契约，不取代 Doctor 原有的跨宿主质量、安全、指针和扫描检查。

### 盘点多个 Skill

当传入的是宿主 Skill 根目录或仓库父目录时，用扫描模式。主机目录通常只看直接入口：

```bash
python3 check.py --scan --direct ~/.claude/skills --json
python3 check.py --scan /path/to/repository --json
python3 check.py --scan /path/to/codex-skills --profile codex --json
```

默认递归扫描会跳过测试夹具和构建目录；direct 模式只检查根目录下一层的宿主入口。
两种模式都会识别隐藏宿主目录、断开的软链、真实入口去重和重复 name。自动化应读取 JSON
里的 gate 字段；score/grade 只是质量参考，不能替代门禁判断。

### Docker（不想装 Python 也能跑）

```bash
# 拉官方镜像直接用（打 v* tag 时 GitHub Actions 自动发布到 GHCR）
docker run --rm -v "$PWD:/work" ghcr.io/huiyonghkw/hekouwang-claude-skill-doctor-skill

# 或本地自建
docker build -t claude-skill-doctor .
docker run --rm -v "$PWD:/work" claude-skill-doctor            # 体检挂载的 skill
docker run --rm -v "$PWD:/work" claude-skill-doctor /work --json
```

### 接进 CI 卡关（GitHub Actions 示例）

```yaml
- uses: actions/setup-python@v5
  with: { python-version: "3.x" }
- name: SKILL.md 体检（不合格则拦 PR）
  run: |
    curl -sO https://raw.githubusercontent.com/huiyonghkw/hekouwang-claude-skill-doctor-skill/main/check.py
    python3 check.py path/to/your/skill
```

本仓库自身的 CI 见 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)（语法 + good/bad 夹具 + JSON 合法性）。

## 检查项与门禁

| 权重 | 项 |
|---|---|
| **1.5（核心）** | 无硬编码密钥 · frontmatter 必填合法 · description 含「何时用」 · SKILL.md ≤500 行 · 渐进披露(拆 references/) · 可移植(无硬编码绝对路径) · 别替模型补它已会的 |
| 1.0（标准） | description ≤1024 · 指针无死链 · 脚本外置 scripts/ |
| 0.6（加内容） | allowed-tools 最小化 · 配套文档(README+CHANGELOG) |

分档：A ≥85 · B ≥70 · C ≥50 · D <50。

启用 `--profile codex` 时，

_meta.json

{
  "ownerId": "kn73qd1gcmjr446mwcbdxef70x82vxcw",
  "slug": "hekouwang-claude-skill-doctor-skill",
  "version": "1.8.0",
  "publishedAt": 1788078352385
}

Github ReposUpdated 15h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.