BlockWatch
Bind code to its docs and config with <block> annotations, so any drift fails CI or a pre-commit hook immediately.
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.
- 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.
What does this skill do, and when should you use it?
BlockWatch is a Rust-based, language-agnostic linter that enforces rules declared inside HTML-like <block> tags placed in source-file comments, with no config files. It detects co-edit relationships between code and its docs/config (affects), cross-file value equality (same-as), and local constraints like sorted and unique lists, line formats and line counts. It supports 33 languages, and by reading a git diff it validates only the changed blocks, keeping pre-commit and CI checks near-instant. The repository ships an Agent Skill that teaches an AI agent when to add blocks, how to respect existing ones, and how to verify its own edits.
Scans comments for <block ...> tags and enforces their rules: keep-sorted/keep-unique check list ordering and uniqueness; affects requires the referenced named block to change when this block changes in a diff; same-as compares the actual values of two or more blocks (no diff needed); line-pattern and line-count enforce per-line format and bounds; check-ai validates natural-language rules via an LLM (needs an API key), and check-lua runs custom Lua scripts. Run bare to check the whole tree, or pipe a diff with git diff --patch | blockwatch --diff --only-changed to check only touched blocks; blockwatch list dumps all blocks as JSON. It supports --suppress, SARIF output, and severity levels.
- Developers on polyglot codebases: adding an enum variant forces the language list in the README to be updated in the same change.
- Team leads who want 'please sort this' review nits replaced by automatic keep-sorted/keep-unique checks.
- Config-sensitive projects: keep ports and env vars in code equal to their README tables and manifests via same-as.
- Projects wired into pre-commit or GitHub Actions: only diff-touched blocks are validated, keeping checks near-instant.
- First-time bulk annotation of an existing repo: let the agent survey lists, enums and constants and add minimal block tags.
- Maintainers using check-lua: encode domain rules too complex for regex as custom Lua scripts.
What are this skill's strengths and limitations?
- Language-agnostic across 33 languages, no config file — everything is comments and CLI flags.
- Diff-based --only-changed mode keeps validation near-instant for pre-commit and CI.
- Deterministic validators (sorting, uniqueness, patterns, counts) are free, fast, and keyless; check-ai is reserved as a fallback.
- SARIF output, severity levels, and violation suppression make gradual adoption in existing repos practical.
- Deleting a block silently deletes its rule — the run still passes; only blocks pointing at the deleted one fail.
- Files without comment syntax (JSON, CSV, .env) can only be linked via whole-file affects.
- Unsupported extensions are skipped silently; use --verbosity summary to confirm how many files were actually read.
- check-ai needs network access and an API key, and its verdict is non-deterministic — the same block can pass one run and fail the next.
- Only error severity fails the run (exit 1); diffs must carry Git's standard path prefixes, so repos with diff.noprefix need --default-prefix --no-relative.
How do you install this skill?
Install the CLI first: brew install mennanov/blockwatch/blockwatch or cargo install blockwatch (prebuilt binaries are on the Releases page). For Claude Code: /plugin marketplace add mennanov/blockwatch then /plugin install blockwatch@blockwatch. For Cursor, Copilot, Codex and other setups, see docs/agents.md in the repo (those steps are not detailed in this source).
How do you use this skill?
While writing or modifying code that matches the value catalog (a list that must stay sorted, an enum mirrored in docs), add the tag in the same edit, e.g. wrap a Python list in # <block keep-sorted keep-unique> / # </block>. Verify with git diff --patch | blockwatch --diff --only-changed. For a first-time pass on a project: survey candidates with rg/grep, add tags, run blockwatch list to confirm they parse, run bare blockwatch to confirm a clean tree, then wire in the provided pre-commit config or the mennanov/blockwatch-action@v1 GitHub Action. When editing files that already contain blocks, never delete the tags and honor directives like affects.
How does this skill compare with similar options?
Unlike single-file style linters such as keep-sorted, BlockWatch's distinguishing capability is cross-file co-edit (affects) and value-equality (same-as) enforcement — it forces code, docs and configuration to change together instead of relying on reviewers to catch drift.