BlockWatch
用 <block> 标注把代码与文档、配置绑定在一起，一旦其中一方漂移，CI 或 pre-commit 立即失败。
技能本身是文档型指令，不索取权限；核心校验器均为本地确定性检查。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 运行记录或完整测试套件源码，证据类型仍以声明与局部材料为主。
- check-ai 会把被扫描块的内容发送到外部 LLM API，勿将其用于含敏感信息的块，且其结果不稳定、需人工复核；该功能在中国大陆网络下可能无法访问。
- check-lua 会执行扫描文件内嵌的脚本；在处理不可信代码（如 fork PR）时务必使用沙箱模式，本审查未独立验证其沙箱强度。
- 发布者身份未经注册表验证；SKILL.md 文件在证据中似乎被截断，安装/CI 章节的完整性未完全核验。
- 本评分为静态源码审查，未执行任何命令；请先在隔离环境中运行 cargo test 与示例验证后再采用。
这个 Skill 能做什么，适合哪些场景？
BlockWatch 是一个用 Rust 编写、语言无关的 linter，通过在注释里声明 HTML 风格的 <block> 标签来执行规则，无需任何配置文件。它能检测代码与其文档/配置之间的共变关系（affects）、跨文件数值一致性（same-as），以及列表排序、去重、行格式和行数等本地约束。支持 33 种语言，通过读取 git diff 可以只校验被改动的块，使 pre-commit 和 CI 校验几乎瞬时完成。仓库自带的 Agent Skill 教 AI 代理何时添加块、如何遵守已有块并自行验证改动。
扫描源码注释中的 <block ...> 标签并执行其声明的规则：keep-sorted/keep-unique 检查列表排序与去重；affects 在 diff 中要求被引用的命名块同步修改；same-as 比较两个块的实际值是否一致（无需 diff）；line-pattern、line-count 强制行级格式与数量；check-ai 用 LLM 执行自然语言规则（需 API key），check-lua 运行自定义 Lua 脚本。可直接运行校验全树，或用 git diff --patch | blockwatch --diff --only-changed 只校验改动涉及的块；blockwatch list 以 JSON 输出所有块。支持 --suppress 抑制违规、SARIF 输出、severity 分级。
- 维护多语言代码库的开发者：枚举新增变体时强制 README 中的语言列表同步更新。
- 团队负责人：把'请排序一下'这类 review 意见前置为 keep-sorted/keep-unique 自动检查。
- 配置敏感项目：保证代码中的端口、环境变量与 README 表格、manifest 中的数值一致（same-as）。
- 接入 pre-commit 或 GitHub Actions 的项目：只校验 diff 涉及的块，保持检查近瞬时。
- 已有代码库的首次批量标注：让代理扫描列表、枚举、常量并补齐最小化块标签。
- 使用 check-lua 的维护者：为正则表达不了的领域规则编写自定义校验脚本。
这个 Skill 有哪些优点和局限？
- 语言无关，支持 33 种语言，无配置文件，全部通过注释标签和 CLI 参数表达。
- 基于 diff 的 --only-changed 模式使校验接近瞬时，适合 pre-commit 和 CI。
- 确定性校验器（排序、去重、模式、数量）免费快速，无需 API key；check-ai 仅作兜底。
- 支持 SARIF 输出、severity 分级、违规抑制，便于渐进式接入已有代码库。
- 删除块标签会静默删除其规则，运行仍通过；只有指向该块的引用才会报错。
- 无法放注释的文件（JSON、CSV、.env）只能用整文件级 affects 链接。
- 不支持的扩展名被静默跳过，需用 --verbosity summary 确认实际读取的文件数。
- check-ai 依赖网络与 API key，且同一块可能一次通过一次失败，结果不稳定。
- 仅 error 级别会使退出码为 1；diff 需带 Git 标准路径前缀，设置了 diff.noprefix 的仓库需加 --default-prefix --no-relative。
如何安装这个 Skill？
先安装 CLI：brew install mennanov/blockwatch/blockwatch 或 cargo install blockwatch（也有预编译二进制）。对 Claude Code：/plugin marketplace add mennanov/blockwatch 然后 /plugin install blockwatch@blockwatch。Cursor、Copilot、Codex 等其他安装方式见仓库 docs/agents.md（具体步骤未在本源中列出）。
如何使用这个 Skill？
在编写或修改代码时，若内容命中块的价值目录（如需保持排序的列表、与文档共变的枚举），当场在注释中加入对应标签，例如在 Python 列表两侧加 # <block keep-sorted keep-unique> / # </block>。验证：git diff --patch | blockwatch --diff --only-changed。首次接入项目：用 rg/grep 找候选位置，加标签后运行 blockwatch list 确认解析、再跑 blockwatch 确认全树通过，然后按仓库示例配置 pre-commit 钩子或 mennanov/blockwatch-action@v1 的 GitHub Actions 工作流。编辑已含块的文件时，绝不能删除块标签，且必须遵守 affects 等指令。
这个 Skill 与同类方案有什么区别？
与 keep-sorted 这类只做单文件格式检查的 linter 不同，BlockWatch 的核心差异在于跨文件的共变（affects）与数值一致性（same-as）校验——它强制代码、文档和配置一起变动，而不是仅在 review 中被人肉发现。