docs-tools

v0.0.2

Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.

Important: Always run Claude Code from a terminal in the root of the documentation repository you are working on. The docs-tools commands and agents operate on the current working directory, they read local files, check git branches, and write output relative to the repo root.

Prerequisites

Configure the Red Hat Docs Agent Tools marketplace
Install GitHub CLI (gh)
```
gh auth login
```

Install system dependencies

# RHEL/Fedora
sudo dnf install python3 jq curl

Install gcloud CLI

gcloud auth login --enable-gdrive-access

Install Python packages
```
python3 -m pip install python-pptx PyGithub python-gitlab jira pyyaml ratelimit requests beautifulsoup4 html2text
```
The python-pptx package is only required for Google Slides conversion. Google Docs and Sheets conversion has no extra dependencies.

Create an ~/.env file with your tokens:

JIRA_AUTH_TOKEN=your_jira_token
# Optional: defaults to https://issues.redhat.com if not set
JIRA_URL=https://issues.redhat.com
# Required scopes: "repo" for private repos, "public_repo" for public repos
GITHUB_TOKEN=your_github_pat
# Required scope: "api"
GITLAB_TOKEN=your_gitlab_pat

Add the following to the end of your ~/.bashrc (Linux) or ~/.zshrc (macOS):
```
if [ -f ~/.env ]; then
    set -a
    source ~/.env
    set +a
fi
```
Restart your terminal and Claude Code for changes to take effect.

The requirements-analyst agent references skills from these companion plugins. Add the marketplace first, then install the plugins:

# Add the related marketplace
/plugin marketplace add https://gitlab.cee.redhat.com/aireilly/marketplace.git

# Install JIRA and Red Hat docs plugins
/plugin install docs-rh-plugins@redhat-docs-marketplace
/plugin install pr-plugins@redhat-docs-marketplace

Plugin	Skills used
pr-plugins	`jira-reader`, `git-pr-reader`
docs-rh-plugins	`article-extractor`, `redhat-docs-toc`

Install

/plugin install docs-tools@redhat-docs-agent-tools

Update

/plugin marketplace update redhat-docs-agent-tools

Commands

/docs-tools:docs-review [--local | --pr <url> [--post-comments] | --action-comments [url]] [--threshold <0-100>]

Multi-agent documentation review with confidence scoring — local, PR/MR, or action comments

/docs-tools:docs-workflow [action] <ticket> [--pr <url>] [--create-jira <PROJECT>] [--mkdocs]

Run the multi-stage documentation workflow for a JIRA ticket. Orchestrates agents sequentially — requirements analysis, planning, writing, technical review, and style review

Agents

Agent	Description
`docs-planner`	Use PROACTIVELY when planning documentation structure, performing gap analysis, or creating documentation plans. Analyzes codebases, existing docs, JIRA tickets, and requirements to create comprehensive documentation plans with JTBD framework. MUST BE USED for any documentation planning or content architecture task.
`docs-reviewer`	Use PROACTIVELY when reviewing documentation for style guide compliance. Uses Vale linting and 18 style guide review skills (IBM Style Guide + Red Hat SSG) to review AsciiDoc files, edit in place, and generate review reports. MUST BE USED for any style review or documentation quality check.
`docs-writer`	Use PROACTIVELY when writing or drafting documentation. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules in AsciiDoc (default) or Material for MkDocs Markdown format. MUST BE USED for any documentation writing, drafting, or content creation task.
`requirements-analyst`	Use PROACTIVELY when analyzing JIRA tickets, PRs, or engineering specs for documentation requirements. Parses JIRA issues, PRs, Google Docs, and engineering specs to extract documentation requirements and map them to modular documentation modules. Uses web search to expand research with external sources. MUST BE USED for any requirements analysis or documentation scoping task.
`technical-reviewer`	Use PROACTIVELY when reviewing documentation for technical accuracy. Reads docs as a developer or architect consumer to catch issues that style-focused review misses — broken code examples, missing prerequisites, incorrect commands, false architectural claims, and absent failure paths. MUST BE USED for technical review of procedures, API docs, tutorials, operator guides, and conceptual overviews.

Skills

Skill	Description
`docs-convert-gdoc-md`	Read a Google Docs document, Google Slides presentation, or Google Sheets spreadsheet and output as Markdown or CSV. Use this skill when asked to read, fetch, import, or convert a Google Doc, Google Slides, or Google Sheets URL.
`docs-review-content-quality`	Review documentation for content quality — logical flow, user journey alignment, scannability, conciseness, fluff removal, and customer focus. Use this skill whenever someone asks to check if docs are well-organized, too wordy, have unnecessary content, lack logical flow, or need tightening. Also use for content quality peer reviews, minimalism checks, or when asked to "cut the fluff" or "make it more concise.
`docs-review-modular-docs`	Review AsciiDoc (.adoc) files for Red Hat modular documentation compliance — module types (concept, procedure, reference), assembly structure, anchor IDs, context variables, leveloffset, and include directives. Use this skill whenever someone asks about modular docs, checks .adoc file structure, asks if a module is the right type, needs to verify anchor IDs have _{context}, or reviews assemblies. Also triggers for questions about concept vs procedure vs reference modules, prerequisites formatting, or Red Hat doc structure.
`ibm-sg-audience-and-medium`	Review documentation for IBM Style Guide audience and medium issues — accessibility (alt text, color, headings), global audience readiness (idioms, date formats, cultural references), tone (active voice, no "please" or "simply"), AI assistant style, marketing claims, and mobile/video content. Use this skill when reviewing docs for accessibility, internationalization, tone problems, or audience appropriateness. For Red Hat docs, prefer the rh-ssg-accessibility skill for accessibility-specific checks.
`ibm-sg-language-and-grammar`	Review documentation for IBM Style Guide language and grammar — abbreviations/acronyms, capitalization, active voice, inclusive language (master/slave, blacklist/whitelist, gendered pronouns), contractions, anthropomorphism, and preferred terminology (avoid "utilize," "leverage," "via," "in order to," "please"). Use this skill when checking grammar, word choice, inclusive language, or terminology compliance. For Red Hat docs, the rh-ssg-grammar-and-language skill takes precedence on conscious language and contractions.
`ibm-sg-legal-information`	Review documentation for IBM Style Guide legal issues — unsubstantiated claims, superlatives, trademarks (™/® usage), copyright notices, personal information (PII in examples), and republishing/attribution of external content. Use this skill when checking for legal risks, trademark compliance, PII exposure in examples, unsupported marketing claims, or content attribution issues. For Red Hat docs, the rh-ssg-legal-and-support skill takes precedence on Technology Preview and Developer Preview.
`ibm-sg-numbers-and-measurement`	Review documentation for IBM Style Guide number and measurement formatting — numerals vs. spelled-out numbers, commas in large numbers, currency codes (USD/EUR), date formats, 24-hour time, units of measurement (KB/MB/GB with spaces), IEC binary prefixes (KiB/MiB/GiB), and phone numbers. Use this skill when checking number formatting, date/time consistency, unit abbreviations, or measurement conventions in documentation.
`ibm-sg-punctuation`	Review documentation for IBM Style Guide punctuation — serial/Oxford commas, colons before lists, em dashes vs. en dashes vs. hyphens, compound adjective hyphenation, quotation marks (US style), semicolon avoidance, ellipses, exclamation points, parentheses, slashes ("and/or"), and period consistency in lists. Use this skill when checking punctuation, hyphenation, comma usage, dash types, or list punctuation consistency.
`ibm-sg-references`	Review documentation for IBM Style Guide reference issues — citations, footnotes, geographic locations, product and service names (official capitalization, trademark usage), product version formatting ("version 4.12 and later" not "recent versions"), and name/title conventions. Use this skill when checking product names, version references, citation formatting, geographic references, or footnote usage in documentation.
`ibm-sg-structure-and-format`	Review documentation for IBM Style Guide structure and format — headings (sentence case, no gerunds), lists (parallel structure, lead-in sentences), procedures (imperative verbs, one action per step, max 9 steps), tables (headers, alignment, captions), notes/warnings/tips, bold/monospace/italic formatting, and figures with alt text. Use this skill when checking doc structure, heading style, list formatting, procedure steps, table layout, or emphasis conventions. For Red Hat docs, the rh-ssg-structure and rh-ssg-formatting skills take precedence.
`ibm-sg-technical-elements`	Review documentation for IBM Style Guide technical elements — code examples (language tags, realistic values, RFC 2606/5737 addresses), command-line formatting (prompts, line continuation), command syntax notation (, [optional], {choice1
`rh-ssg-accessibility`	Review Red Hat documentation for accessibility compliance (WCAG) — alt text for images/icons, color not as sole information carrier, no directional language ("left"/"right"/"above"), descriptive link text (no "click here"), table structure (no irregular headers, no blank header cells), and correct heading nesting. Use this skill whenever checking Red Hat docs for accessibility, screen reader compatibility, alt text, link text, or WCAG compliance. This skill takes precedence over ibm-sg-audience-and-medium for accessibility checks on Red Hat content.
`rh-ssg-formatting`	Review Red Hat documentation for SSG formatting compliance — code blocks (one command per step, bold via subs="+quotes", separate input/output), user-replaced values (angle brackets, italics, underscores), sentence-style capitalization in titles, product name/version attributes (not hard-coded), date formats ("3 October 2019"), single-step procedures (bullet not number), non-breaking spaces in "Red Hat", and man page references. Use this skill when checking Red Hat docs for code block formatting, placeholder values, title capitalization, product name attributes, or date formats.
`rh-ssg-grammar-and-language`	Review Red Hat documentation for SSG grammar and language compliance — conscious language (no blacklist/whitelist, no master/slave), no contractions in product docs, conversational style levels, minimalism principles (action-oriented, scannable, concise), animate vs. inanimate user pronouns (who vs. that), and homograph avoidance. Use this skill when checking Red Hat docs for inclusive/conscious language, contraction usage, minimalism, wordiness, or grammar compliance. This skill takes precedence over ibm-sg-language-and-grammar for Red Hat content.
`rh-ssg-gui-and-links`	Review Red Hat documentation for SSG graphical interface and link compliance — UI element formatting (bold text, correct verbs: click/select/enter), screenshot guidelines, text entry ("enter" not "type"), cross-reference format (xref), external link rules (no bare URLs, no shorteners, descriptive link text), Red Hat docs links (use "latest" in URL path), and Knowledgebase article link formatting. Use this skill when checking Red Hat docs for UI element formatting, link text, cross-references, screenshot usage, or URL formatting. Takes precedence over ibm-sg-technical-elements for UI and link checks on Red Hat content.
`rh-ssg-legal-and-support`	Review Red Hat documentation for SSG legal and support compliance — no cost/pricing references, no future release promises, Developer Preview requirements (IMPORTANT admonition, no "supported"), and Technology Preview requirements (IMPORTANT admonition, never "Tech Preview" or "Technical Preview", no "supported as a Technology Preview"). Use this skill when checking Red Hat docs for Technology Preview, Developer Preview, TP/DP admonitions, cost language, future release statements, or support scope compliance. Takes precedence over ibm-sg-legal-information for Red Hat content.
`rh-ssg-release-notes`	Review Red Hat release notes for SSG compliance — tense rules (present default, past for "before this update"), informative headings (sentence case, no gerunds, under 120 chars), Jira references on known/fixed issues, AsciiDoc formatting (description lists, + attachment), and release note types: new features, enhancements, rebases (X.Y.Z format), Technology Preview entries, deprecated features, removed features, known issues (Cause > Consequence > Workaround > Result), and fixed issues (CCFR pattern). Use this skill whenever reviewing, writing, or checking release notes for any Red Hat product.
`rh-ssg-structure`	Review Red Hat documentation for SSG structural compliance — admonitions (NOTE/IMPORTANT/WARNING/TIP only, no CAUTION, no clustering, modules never start with admonitions), lead-in sentences (only when needed after Prerequisites/Procedure headings), prerequisites (written as completed states not imperative commands), and short descriptions/abstracts (2-3 sentences, customer-centric, no self-referential language). Use this skill when checking Red Hat docs for admonition usage, prerequisite formatting, short descriptions, or structural compliance. Takes precedence over ibm-sg-structure-and-format for Red Hat content.
`rh-ssg-technical-examples`	Review Red Hat documentation for SSG technical example compliance — root privilege commands (use sudo with $ prompt, not su -), YAML ellipses (use "# ..." not bare "..."), IP addresses (RFC 5737 for IPv4, RFC 3849 for IPv6), MAC addresses (RFC 7042), code block quality (accurate, copy-paste friendly), and syntax highlighting (never use "bash" for terminal commands — use "terminal", "console", or omit). Use this skill when checking Red Hat docs for code examples, IP/MAC addresses in examples, sudo usage, YAML formatting, or source language tags on code blocks. Takes precedence over ibm-sg-technical-elements for Red Hat content.