跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

blockwatch

Use when writing or modifying code in a project that uses BlockWatch — proactively link co-dependent code with `<block affects=...>`/`<block name=...>` so it catches drift when one side changes without the other (an enum and its docs, a constant and its config), or assert two places hold the same value with `<block same-as=...>`. Also for lists that must stay sorted/unique or values with a strict format/size, and when editing files that contain `<block ...>` tags (affects, same-as, keep-sorted, keep-unique, line-pattern, line-count, check-ai, check-lua).

mennanov · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add mennanov/blockwatch --skill blockwatch

技能说明


name: blockwatch description: Use when writing or modifying code in a project that uses BlockWatch — proactively link co-dependent code with <block affects=...>/<block name=...> so it catches drift when one side changes without the other (an enum and its docs, a constant and its config), or assert two places hold the same value with <block same-as=...>. Also for lists that must stay sorted/unique or values with a strict format/size, and when editing files that contain <block ...> tags (affects, same-as, keep-sorted, keep-unique, line-pattern, line-count, check-ai, check-lua).

BlockWatch

BlockWatch is a language-agnostic linter that enforces rules declared inside HTML-like <block ...> tags placed in source-file comments. It works across Rust, Python, JS/TS, Go, Java, Markdown, YAML, TOML, HTML, and more. By default it checks the whole tree; given a git diff on stdin it can instead check only the blocks that diff changed.

Use this skill in three situations:

  • As you write code (the default): the moment you write something a block would guard, add the block in the same change — don't wait for a separate pass.
  • First-time / bulk pass: annotating an existing project that has no blocks yet.
  • Maintaining blocks: keeping existing blocks valid when you edit files that already contain them.

Two rules apply to all three:

  • High-value only. A block must catch a real mistake someone could plausibly make, not decorate. Too many blocks create noise and get ignored. When in doubt, leave it out.
  • Only in projects that use BlockWatch. This skill being installed, or existing <block> tags in the tree, means the project opted in. Don't add blocks to a project that doesn't use the tool.

Annotate as you write code

This is the primary way blocks should get added: incrementally, as part of normal coding. Whenever you write or change code matching a row in Where blocks add value (below), add the tag right then, using the Validator reference for the syntax.

Introduce a list that should stay ordered → wrap it in keep-sorted in the same edit. Add a fact that also lives in the docs or config → add affects in the same edit. Retrofitting later is exactly the cost this avoids.

Then run git diff --patch | blockwatch --diff --only-changed to confirm the new tags pass (see Running and verifying).

Annotating a new project

  1. Survey the repo for the patterns in the catalog below. Read the code and the docs/config; use rg/grep to find lists, enums, match arms, tables, and constants.
  2. For each candidate, add the minimal block tag using the comment syntax of that file's language.
  3. Run blockwatch list to confirm every new tag parses and is recognized, then run blockwatch to confirm all blocks pass on the current (clean) tree. Fix any tag you placed on already-inconsistent content.
  4. Commit, then wire BlockWatch into hooks/CI (see below) so the rules are enforced from now on.

Where blocks add value (catalog)

You see...AddWhy
A hand-maintained list/enum/match that should stay ordered (dependencies, CLI flags, feature lists, route tables)keep-sortedEliminates "please sort this" review nits
A list that must not repeat (allowlists, IDs, registered names)keep-uniquePrevents accidental duplicates
The same fact in two places — an enum and its docs, a version constant and a changelog row, a config key and its README tableaffects + nameForces docs/config to be updated alongside code
The same value duplicated across places — a constant and its docs, a port in code and in a manifest, an env-var set and its README tablesame-as + nameFails when the copies actually disagree, not just when one side is touched
A list whose items have a strict format (slugs, semver, env-var names)line-pattern="<regex>"Catches typos at the source
A block that must not grow past N lines (public API surface, a switch mapped to a fixed enum)line-count="<=N"Flags unbounded growth
Prose or config with a natural-language rule ("must mention X", "no TODOs left")check-ai="..."Rules regex can't express
Domain logic too complex for regexcheck-lua="script.lua"Custom programmable checks

Prefer the deterministic validators (keep-sorted, keep-unique, affects, same-as, line-pattern, line-count) first — they are free, fast, and need no API keys. Reserve check-ai for rules the cheaper validators genuinely can't express.

When two blocks should hold the same value, prefer same-as over a bare affects: affects only notices that o

阅读完整来源 ↗