这个 Skill 能做什么，适合哪些场景？
BlockWatch 是一个语言无关的 linter，它读取写在源码注释里的 HTML 风格 <block ...> 标签，并据此强制执行规则：强制关联文件一起修改（affects）、断言多处值一致（same-as）、保持列表有序或唯一、校验行格式与行数，甚至用 LLM 或 Lua 做自定义校验。它支持 33 种语言，不需要任何配置文件，规则全部内联在代码注释中。默认检查整个仓库树；配合 --diff --only-changed 时只检查被 diff 触及的块，速度快到可以放进 pre-commit 钩子。这个技能教 Agent 何时该加块、加哪种块，以及如何在编辑后自行验证。
- 在编写或修改代码时，当场用 keep-sorted、keep-unique、affects、same-as、line-pattern、line-count 等标签包裹值得守护的内容
- 为已有项目做首次批量标注：扫描列表、枚举、match 分支、常量和文档表格，逐一加最简标签
- 编辑含 <block> 的文件时遵守既有规则：不删标签、保持有序/唯一、满足 affects 的联动修改
- 编辑后运行 git diff --patch | blockwatch --diff --only-changed 验证改动未破坏任何规则
- 一次性接入 pre-commit 钩子或 GitHub Actions（mennanov/blockwatch-action@v1），让规则长期生效
- 维护公共 API 或枚举的开发者：修改 Rust 枚举后，README 中对应的语言列表必须同步更新，affects 会强制两者一起改
- 配置与代码中重复出现同一值的场景：代码里的端口与 manifest 中的端口用 same-as 比对实际值，不一致即失败
- 手写的依赖列表、CLI 参数表、路由表希望始终有序：keep-sorted 消除代码评审中的'请排序'意见
- allowlist、ID、注册名列表禁止重复：keep-unique 在源头阻止意外重复
- slug、semver、环境变量名等有严格格式的行：line-pattern 在源头拦截拼写错误
- 接入 BlockWatch 的团队在 CI 中跑 mennanov/blockwatch-action@v1，对每个 PR 的 diff 做漂移检查
- 没有使用 BlockWatch 的项目——技能明确规定不要在未采用该工具的仓库中添加 <block> 标签
- JSON、CSV、.env 等不支持注释的文件——无法在文件内部放置标签，只能通过整文件级 affects 间接关联
- 不想维护内联注释规则的团队——若偏好集中式配置文件，本工具刻意不提供该选项
如何安装这个 Skill？
- check-ai 会把被扫描块的内容发送到外部 LLM API，勿将其用于含敏感信息的块，且其结果不稳定、需人工复核；该功能在中国大陆网络下可能无法访问。
- check-lua 会执行扫描文件内嵌的脚本；在处理不可信代码（如 fork PR）时务必使用沙箱模式，本审查未独立验证其沙箱强度。
- 发布者身份未经注册表验证；SKILL.md 文件在证据中似乎被截断，安装/CI 章节的完整性未完全核验。
- 本评分为静态源码审查，未执行任何命令；请先在隔离环境中运行 cargo test 与示例验证后再采用。
- Shell / 命令行
- 本地文件系统
blockwatch CLI (cargo install blockwatch or brew install mennanov/blockwatch/blockwatch)git (for --diff mode)
工具本身支持两种安装途径（来源：README）：
macOS / Linux (Homebrew)
brew install mennanov/blockwatch/blockwatch从源码 (Cargo)
cargo install blockwatch预编译二进制可在 GitHub Releases 页面下载。在 Claude Code 中安装该技能：
Claude Code
/plugin marketplace add mennanov/blockwatch
/plugin install blockwatch@blockwatchCursor、Copilot、Codex 等其他宿主的接入方式见仓库的 docs/agents.md。
如何使用这个 Skill？
安装后，把下面任意一句发给 Agent 即可触发：
- 给 src/config.rs 里的 MAX_RETRIES 常量和 README 中的配置表格加一组 affects 块，然后跑 git diff --patch | blockwatch --diff --only-changed 验证
- 扫描这个仓库，找出所有应该用 keep-sorted 或 keep-unique 守护的手写列表并加上标签
- 我刚改了 Language 枚举，帮我同步更新 README 里的 supported-languages 块，直到 blockwatch --diff 通过
- 给这个项目配置 pre-commit 钩子和 GitHub Actions 工作流，让 blockwatch 只校验 diff 触及的块
技能在三种情况下触发：编写代码时顺手加块（默认）、为无块的存量项目做首次标注、维护已有块。核心流程：
# 检查仓库中所有块
blockwatch# 只检查被 diff 触及的块（快，适合 pre-commit）
git diff --patch | blockwatch --diff --only-changed
# 检查全部块并启用需要 diff 的规则（如 affects）
git diff --patch | blockwatch --diff
# 检查暂存区改动
git diff --cached --patch | blockwatch --diff --only-changed
# 以 JSON 列出所有已识别的块（审计/调试）
blockwatch list
# 限制到指定 glob 或排除路径
blockwatch "src//*.rs" "/*.md"
blockwatch --ignore "/generated/"
要点：仅在 --diff 时读取 stdin；管道传入空内容、ANSI 着色或非 diff 内容都会报错而非跳过。规则越简单越好——优先用确定性校验器，check-ai 需要设置 BLOCKWATCH_AI_API_KEY 且结果不稳定，仅在前者无法表达规则时使用。报错时读消息、修复排序/重复/格式/同步问题后重跑直至通过。
这个 Skill 有哪些优点和局限？
- 支持 33 种语言，规则内联在注释中，零配置文件，配置本身不会与代码漂移
- same-as 无需 diff 即可比对实际值，能发现 diff 模式漏掉的静默漂移
- --diff --only-changed 只校验改动过的块，pre-commit 和 CI 中几乎瞬时完成
- 确定性校验器（排序、唯一、行格式等）免费快速；违反可按严重级别降级，还支持 --suppress 排除特定违规而不改源码
- 删除块会静默删除其规则：整次运行照样通过，没有任何提示（指向被删块的引用仍会失败）
- JSON、CSV、.env 等无注释格式无法放置标签，只能整文件级关联
- 不支持的扩展名被静默跳过——读到零文件的运行与'没有问题'的运行看起来一样，需 --verbosity summary 核实
- check-ai 依赖网络与 API key，同一块可能一次通过一次失败，结果不可靠
- 仓库支持列表明确排除 .hpp/.hxx/.cxx 等扩展，需手动用 -E 映射
这个 Skill 与同类方案有什么区别？
与相关 Skills 并排比较；分数均按同一 FSRS 标准得出。
| Skill | FS 评分 | Star 数 | 最近更新 | License |
|---|---|---|---|---|
| BlockWatch 本页 | 67 · 推荐 | ★ 29 | 11 天前 | MIT |
| Pulser — SKILL.md 诊断器 | 50 · 谨慎使用 | ★ 18 | 3 个月前 | MIT |
| CodeRabbit 代码审查技能 | 53 · 谨慎使用 | ★ 35 | 2 个月前 | Unlicense |
| REA 工具设计技能 | 51 · 谨慎使用 | ★ 238k | 11 天前 | MIT |
| Codex CLI 构建器 ✓ OpenAI · 官方 | 55 · 谨慎使用 | ★ 28k | 4 个月前 | — |
README 将其定位为替代'代码评审中反复挑剔'的工具：keep-sorted 替代'请把这个列表排序'的评审意见，affects/same-as 替代人工检查文档与代码是否同步。与 central 配置文件方案相比，README 明确指出刻意不提供配置文件，因为集中配置本身也会漂移——这正是本工具要解决的问题。
FollowSkills 如何评估这个 Skill？
技能本身是文档型指令，不索取权限；核心校验器均为本地确定性检查。check-ai 会把块内容发送到外部 LLM API（需 BLOCKWATCH_AI_API_KEY），文档已明确披露其非确定性；check-lua 在 fork PR 场景下的沙箱/非沙箱区分在 blockwatch.yml 中有明确信任模型。扣分：check-lua 允许运行文件内嵌脚本，安全依赖工具侧实现且本仓库内未完整审计；API 密钥经环境变量传递的完整数据流说明有限。
文档内部自洽，覆盖了大量边界情况（diff 前缀、stdin 空/着色、keep-sorted-format 的硬错误、line-pattern 引号陷阱）并给出可诊断的失败反馈；仓库含 CI（blockwatch.yml、CodeQL）与测试数据（tests/testdata），支持高于纯静态锚点的评分。扣分：静态审查未执行，关键路径复现与失败输出质量未经独立验证；check-ai 结果本身非确定。
触发条件写得非常精确（frontmatter description 枚举场景与标签类型），明确适用边界（仅在已采用 BlockWatch 的项目中使用、高价值才加块），三种使用场景清晰。扣分：check-ai 依赖境外 LLM API，在中国大陆网络下不可用或受限；Lua 校验器对使用者的编程能力有隐性门槛。
MIT 许可清晰，版本化（Cargo.toml 0.5.3、pre-commit rev 指引）、安装说明（brew/cargo/预编译二进制）、已知限制章节诚实完整，文档分层（SKILL.md → docs/validators）。扣分：发布者身份未经验证、无明确的维护责任与更新路径承诺；本次提供的 SKILL.md 在 GitHub Actions 章节处截断，完整性核验受限；无变更日志证据。
技能解决真实问题（代码与文档漂移），与手动方式相比边际价值明确：增量注释成本低、CI 集成近乎即时，README 中的实际 JSON 输出示例展示可直接可用的结果。扣分：静态审查无法验证实际输出可用性；check-ai 结果需人工复核，部分价值依赖项目已存在的注释。
仓库内有交叉印证材料：README 使用示例与输出、CI 工作流、测试数据文件、Cargo.toml 依赖清单、crates.io 徽章。扣分：静态审查未能独立复现测试，未见到实际通过的 CI 运行记录或完整测试套件源码，证据类型仍以声明与局部材料为主。
点击维度查看打分理由
证据充分度：低 — 主要依赖静态检查、作者材料或有限演示；适合发现线索，不适合做高风险决策。
查看完整评分方法 →