What does this skill do, and when should you use it?
BlockWatch is a language-agnostic linter that enforces rules declared in HTML-like <block ...> tags placed inside source comments. It can force linked files to change together (affects), assert that multiple places hold the same value (same-as), keep lists sorted and unique, and validate line formats, line counts, natural-language rules (via LLM), or custom Lua checks. It supports 33 languages, needs no config file — every rule lives inline where it guards. A bare run checks the whole tree; with --diff --only-changed it validates only the blocks a diff touched, fast enough for pre-commit hooks. This skill teaches an agent when a block is worth adding, which validator to use, and how to verify its own edits.
- Annotates code as it is written: wraps lists, enums, constants, and doc tables in keep-sorted, keep-unique, affects, same-as, line-pattern, line-count tags in the same change
- Runs a first-time bulk pass over an un-annotated project, surveying lists, match arms, tables, and constants with rg/grep
- Maintains existing blocks during edits: never deletes tags, respects ordering/uniqueness/pattern rules, and honors affects by co-editing the linked block
- Verifies edits with git diff --patch | blockwatch --diff --only-changed and iterates until it passes
- Wires enforcement into pre-commit hooks and GitHub Actions (mennanov/blockwatch-action@v1) once, after annotating
- A developer maintaining a public enum: adding a Go variant to the Rust enum must also update the language list in README.md — affects fails the run until both change
- A value duplicated across code and config: a port in source and in a manifest compared with same-as, which fails when the copies actually disagree — no diff needed
- Hand-maintained dependency lists, CLI flags, or route tables that must stay ordered: keep-sorted eliminates 'please sort this' review nits
- Allowlists, IDs, or registered names that must not repeat: keep-unique catches accidental duplicates at the source
- Lines with a strict format such as slugs, semver, or env-var names: line-pattern catches typos where they happen
- A team validating every PR diff in CI via the blockwatch GitHub Action, with a periodic bare run as an extra safety net
- Projects that don't use BlockWatch — the skill explicitly says not to add <block> tags to repositories that haven't opted in
- JSON, CSV, and .env files — they have nowhere to put a tag; link to them only with a whole-file affects
- Teams that want a central config file — the tool deliberately ships none, by design
How do you install this skill?
- check-ai sends scanned block content to an external LLM API; do not use it on blocks containing sensitive data, expect nondeterministic results, and note it may be unreachable from mainland-China networks.
- check-lua executes scripts embedded in scanned files; always use sandboxed mode for untrusted code (e.g., fork PRs) — sandbox strength was not independently verified in this review.
- Publisher identity is unverified; the provided SKILL.md appears truncated mid-file, so completeness of the installation/CI sections could not be fully confirmed.
- This is a static source review with nothing executed; run cargo test and the examples in an isolated environment before adopting.
- Shell / CLI
- Local filesystem
blockwatch CLI (cargo install blockwatch or brew install mennanov/blockwatch/blockwatch)git (for --diff mode)
The CLI has two documented install routes (per the README):
macOS / Linux (Homebrew)
brew install mennanov/blockwatch/blockwatchFrom source (Cargo)
cargo install blockwatchPrebuilt binaries are on the GitHub Releases page. Installing the skill in Claude Code:
Claude Code
/plugin marketplace add mennanov/blockwatch
/plugin install blockwatch@blockwatchFor Cursor, Copilot, Codex, and other hosts, see docs/agents.md in the repository.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Add affects blocks linking the MAX_RETRIES constant in src/config.rs to its README config table, then verify with git diff --patch | blockwatch --diff --only-changed
- Survey this repo for hand-maintained lists that should be guarded with keep-sorted or keep-unique and add the tags
- I just added a variant to the Language enum — update the supported-languages block in README.md until blockwatch --diff passes
- Set up a pre-commit hook and a GitHub Actions workflow so blockwatch only validates the blocks my diff touched
The skill triggers in three situations: annotating as you write code (the default), a first-time bulk pass on an existing project, and maintaining blocks when editing already-annotated files. Core flow:
# Check every block in the tree
blockwatch# Check only the blocks your diff touched (fast, for pre-commit)
git diff --patch | blockwatch --diff --only-changed
# Check everything, enforcing rules that need a diff (like affects)
git diff --patch | blockwatch --diff
# Same, for staged changes
git diff --cached --patch | blockwatch --diff --only-changed
# Dump every discovered block as JSON (audit / debug)
blockwatch list
# Restrict to globs or exclude paths
blockwatch "src//*.rs" "/*.md"
blockwatch --ignore "/generated/"
Notes: stdin is read only with --diff; empty, ANSI-colorized, or non-diff stdin is an error, not a no-op. Prefer the deterministic validators; check-ai requires BLOCKWATCH_AI_API_KEY, makes one network call per block, and is nondeterministic — reserve it for rules regex can't express. On failure, read the message, fix the issue, and re-run until it passes.
What are this skill's strengths and limitations?
- 33 languages supported, zero config files — rules live inline so the configuration itself can't drift
- same-as compares actual values without a diff, catching silent drift a changed-blocks-only check would miss
- --diff --only-changed validates just the touched blocks, near-instant in pre-commit and CI
- Deterministic validators are free and fast; violations can be downgraded by severity or suppressed with --suppress without editing source
- Deleting a block deletes its rule quietly — the run passes with no warning (blocks still pointing at it do fail as missing references)
- Comment-less formats (JSON, CSV, .env) can't hold tags; only whole-file affects can link them
- Unsupported extensions are skipped silently — a run that read nothing looks like a clean run; use --verbosity summary to verify
- check-ai needs network and an API key, and the same block can pass one run and fail the next
- Extensions like .hpp/.hxx/.cxx are explicitly unrecognized and need manual -E mapping
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| BlockWatch this page | 67 · Recommended | ★ 29 | 11d ago | MIT |
| Pulser — SKILL.md Linter | 50 · Use with care | ★ 18 | 3mo ago | MIT |
| CodeRabbit Review Skill | 53 · Use with care | ★ 35 | 2mo ago | Unlicense |
| REA Tool Design Skill | 51 · Use with care | ★ 238k | 11d ago | MIT |
| Codex CLI Builder ✓ OpenAI · Official | 55 · Use with care | ★ 28k | 4mo ago | — |
The README positions BlockWatch against manual code-review nitpicking: keep-sorted replaces 'please sort this' comments, and affects/same-as replace hand-checking that docs and code stay in sync. It also explicitly rejects the central-config-file approach, arguing a config file is one more thing that drifts from the code it describes — the very problem the tool exists to solve.
How did FollowSkills review this skill?
The skill is documentation-only instructions, requests no privileges; core validators are local deterministic checks. check-ai sends block content to an external LLM API (BLOCKWATCH_AI_API_KEY) and this is disclosed, along with its nondeterminism; check-lua trust model for fork PRs is explicit in blockwatch.yml. Deducted: check-lua executes scripts embedded in scanned files, security depends on tool-side sandboxing not fully auditable here; API-key data-flow documentation is limited to env-var passing.
Internally consistent docs covering many edge cases (diff prefixes, empty/colored stdin, hard errors from keep-sorted-format, line-pattern quoting traps) with diagnosable failure feedback; repo has CI (blockwatch.yml, CodeQL) and test data, supporting a score above the pure-static anchor. Deducted: static review did not execute anything, key-path reproduction and failure-output quality unverified; check-ai is inherently nondeterministic.
Trigger conditions are precise (frontmatter description enumerates scenarios and tag types), boundaries are explicit (only in projects using BlockWatch, high-value blocks only), three usage scenarios clear. Deducted: check-ai depends on an overseas LLM API, unavailable or degraded from mainland China; Lua validators carry an implicit programming-skill threshold.
MIT license clear, versioning present (Cargo.toml 0.5.3, pre-commit rev guidance), install paths documented, honest Known Limitations section, layered docs (SKILL.md → docs/validators). Deducted: publisher unverified with no explicit maintenance-ownership or update-path commitment; provided SKILL.md appears truncated mid-way through the GitHub Actions section, limiting completeness checks; no changelog evidence.
Addresses a real problem (code/docs drift) with clear marginal value: low incremental annotation cost, near-instant CI checks, and a realistic JSON output example in README showing directly usable results. Deducted: static review cannot confirm output usability in practice; check-ai results need human review; value partly presupposes pre-existing annotations.
Cross-corroborating material exists in-repo: README usage examples with output, CI workflows, test-data files, dependency manifest, crates.io badges. Deducted: no independent test reproduction in this static pass, no visible passing CI run records or full test-suite source in evidence, so claims rest mainly on declarations plus partial primary material.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →