Claude Skill

docs-review

Grade documentation pages against the docs-quality rule set on demand, in any directory and any markup format (Markdown, MDX, reStructuredText, MyST, AsciiDoc). Use when someone asks to review, check, grade, lint or audit a doc page, a README, a changelog, a docs directory or the

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download grimoire-rs-grimoire-.agents_skills_docs-review-dddf811.zip · 1 KB

Install

skills CLI npx skills add https://github.com/grimoire-rs/grimoire/tree/main/.agents/skills/docs-review
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install grimoire-rs-grimoire@llmmart
Git git clone https://github.com/grimoire-rs/grimoire.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole grimoire-rs/grimoire collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

docs-review

The docs-quality rule loads when an agent edits a page. This skill is the explicit trigger: grade pages nobody is editing, pages in unusual places, and pages in a format the scripts only partly read.

Stop condition

Stop when every target page has a verdict: each finding as path:line: DOC-XXX-nn: message, or clean. Mark any finding no script produced unverified: reading heuristic. Report; never fix unless asked.

1. Pick the targets

  • Named paths or directories: use them as given, whatever their location.
  • Nothing named: the branch diff, git diff --name-only --diff-filter=d "$(git merge-base HEAD origin/HEAD)" -- '*.md' '*.mdx' '*.rst' '*.adoc' '*.asciidoc'.
  • Drop agent config (CLAUDE.md, AGENTS.md, SKILL.md, .claude/, .agents/), vendored copies and build output. The rule excludes them too.

2. Load the rule

Read the installed docs-quality rule index, then only the depth files its routing table names for the target page types. Find it with find . -path '*docs-quality*' -name 'docs-quality.md' -not -path '*/node_modules/*'. Its checks/ directory sits beside it. No hit means the rule is not installed: say grim add ghcr.io/ocx-sh/lore/docs-quality and stop.

3. Run the checks by format

CHECKS below is that checks/ directory. Every script takes explicit paths, so pass the targets rather than --root.

Format Scripted Read by hand
.md, .mdx the whole gate, in the rule's order rows the scripts mark heuristic
.rst, MyST, .adoc doc_declaration.py everything else, or convert first

Markdown and MDX:

python3 "$CHECKS/doc_declaration.py" PAGE...
python3 "$CHECKS/prose.py"           PAGE...
python3 "$CHECKS/page_type.py"       PAGE...
python3 "$CHECKS/landing_check.py"   PAGE...

Add doc_examples.py, nav_depth.py and links_raw.py when the review covers a whole docs tree rather than single pages. Their inputs are a tree.

reStructuredText and AsciiDoc: run doc_declaration.py on the source. The prose and page-type scripts parse Markdown only. When pandoc is on the PATH, convert each page into a scratch directory and run them on the copy:

pandoc -f rst -t gfm PAGE.rst -o "$SCRATCH/PAGE.md"   # asciidoc: asciidoctor -b docbook | pandoc -f docbook

Line numbers from a converted copy point at the copy. Map each finding back to the source line by its quoted text before reporting it. No converter means the non-negotiables are read by hand and every such finding is marked unverified.

4. Report

One line per finding, grouped by page, ordered by the rule's non-negotiable number. End with a count per page. Undeclared pages are listed first, because every type-scoped check skipped them.

Files (grimoire)
  • SKILL.md 3.6 KB
    ---
    name: docs-review
    description: Grade documentation pages against the docs-quality rule set on demand, in any directory and any markup format (Markdown, MDX, reStructuredText, MyST, AsciiDoc). Use when someone asks to review, check, grade, lint or audit a doc page, a README, a changelog, a docs directory or the docs changed on a branch, asks whether a page meets docs-quality, or wants the docs gate run by hand. Not for deciding which pages to write, which is docs-plan, and not for wiring the checks into CI, which is docs-instrument.
    license: Apache-2.0
    metadata:
      summary: Runs the docs-quality gate by hand over named pages or a branch diff, in any directory and any markup format
      keywords: docs,documentation,review,docs-review,check,lint,audit,grade,readme,changelog,markdown,mdx,restructuredtext,rst,myst,asciidoc,adoc,sphinx,antora,doc_type,docs-quality
    ---
    
    # docs-review
    
    The `docs-quality` rule loads when an agent edits a page. This skill is the
    explicit trigger: grade pages nobody is editing, pages in unusual places, and
    pages in a format the scripts only partly read.
    
    ## Stop condition
    
    Stop when every target page has a verdict: each finding as
    `path:line: DOC-XXX-nn: message`, or `clean`. Mark any finding no script
    produced `unverified: reading heuristic`. Report; never fix unless asked.
    
    ## 1. Pick the targets
    
    - Named paths or directories: use them as given, whatever their location.
    - Nothing named: the branch diff,
      `git diff --name-only --diff-filter=d "$(git merge-base HEAD origin/HEAD)" -- '*.md' '*.mdx' '*.rst' '*.adoc' '*.asciidoc'`.
    - Drop agent config (`CLAUDE.md`, `AGENTS.md`, `SKILL.md`, `.claude/`,
      `.agents/`), vendored copies and build output. The rule excludes them too.
    
    ## 2. Load the rule
    
    Read the installed `docs-quality` rule index, then only the depth files its
    routing table names for the target page types. Find it with
    `find . -path '*docs-quality*' -name 'docs-quality.md' -not -path '*/node_modules/*'`.
    Its `checks/` directory sits beside it. No hit means the rule is not
    installed: say `grim add ghcr.io/ocx-sh/lore/docs-quality` and stop.
    
    ## 3. Run the checks by format
    
    `CHECKS` below is that `checks/` directory. Every script takes explicit paths,
    so pass the targets rather than `--root`.
    
    | Format | Scripted | Read by hand |
    |---|---|---|
    | `.md`, `.mdx` | the whole gate, in the rule's order | rows the scripts mark heuristic |
    | `.rst`, MyST, `.adoc` | `doc_declaration.py` | everything else, or convert first |
    
    Markdown and MDX:
    
    ```bash
    python3 "$CHECKS/doc_declaration.py" PAGE...
    python3 "$CHECKS/prose.py"           PAGE...
    python3 "$CHECKS/page_type.py"       PAGE...
    python3 "$CHECKS/landing_check.py"   PAGE...
    ```
    
    Add `doc_examples.py`, `nav_depth.py` and `links_raw.py` when the review covers
    a whole docs tree rather than single pages. Their inputs are a tree.
    
    reStructuredText and AsciiDoc: run `doc_declaration.py` on the source. The
    prose and page-type scripts parse Markdown only. When `pandoc` is on the PATH,
    convert each page into a scratch directory and run them on the copy:
    
    ```bash
    pandoc -f rst -t gfm PAGE.rst -o "$SCRATCH/PAGE.md"   # asciidoc: asciidoctor -b docbook | pandoc -f docbook
    ```
    
    Line numbers from a converted copy point at the copy. Map each finding back to
    the source line by its quoted text before reporting it. No converter means the
    non-negotiables are read by hand and every such finding is marked unverified.
    
    ## 4. Report
    
    One line per finding, grouped by page, ordered by the rule's non-negotiable
    number. End with a count per page. Undeclared pages are listed first, because
    every type-scoped check skipped them.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.