docs-skills

Documentation workflow orchestrator. Reads the step list from .agent_workspace/docs-workflow.yaml (or the plugin default). Runs steps sequentially, manages progress state, handles iteration and confirmation gates. Claude is the orchestrator — the YAML is a step list, not a workflow engine.

Write documentation from a documentation plan. Dispatches the docs-writer agent. Supports AsciiDoc (default) and MkDocs formats. Default placement is UPDATE-IN-PLACE; use --draft for staging area. Also supports fix mode for applying technical review corrections.

Score documentation quality and intent alignment using LLM judge agents (Opus). Dispatches two judge agents in parallel (doc_quality, intent_alignment), extracts specific gaps from AC coverage analysis, and cross-references against scope-req-audit evidence. Produces pass/fail gate with actionable gap list. Iteration logic is owned by the orchestrator, not this skill.

Run code-learner analysis on a source repository for the docs orchestrator workflow. Dispatches a subagent to run learn-code, keeping the heavy orchestration out of the main context. Produces ONBOARDING.md, module registry, per-module summaries, and cross-module relationship data.

Classify JIRA requirements by code evidence status before planning. Uses learn-code analysis data and source code inspection to determine if each requirement is grounded, partial, or absent. Fans out one subagent per requirement for isolated classification. Prevents hallucinated documentation for unimplemented features and surfaces gaps for implemented ones. Conditional on has_source_repo.

Technical accuracy review with optional code-learner claim validation. Iteration logic owned by the orchestrator.

Diagnose a docs-orchestrator pipeline run for failures, bottlenecks, and context-pressure risks. Runs the diagnostics script, drills into failures, and writes a diagnostic report with actionable recommendations.

Fetch unresolved review comments from GitHub PRs or GitLab MRs and action them on local files. Works standalone (interactive) or in CI mode (autonomous). Optionally reads .agent_workspace artifacts for grounding. MUST BE USED when the user asks to action, address, or process review comments on a PR/MR.

Unified interface for GitHub PRs and GitLab MRs: read PR/MR data with file filtering, list changed files, get review comments, post inline review comments, reply to existing comment threads, extract line numbers from diffs, validate comments, auto-detect PR/MR for current branch, and get unified diffs. Automatically detects GitHub vs GitLab from URL. Use this skill for analyzing code changes, posting review feedback, and documentation workflows.

Analyze documentation requirements for a JIRA ticket using a two-pass fanout. Pass 1 dispatches a discovery agent to enumerate requirements. Pass 2 fans out one deep-analysis agent per requirement for isolated, thorough analysis. Assembles the standard requirements.md output. Invoked by the orchestrator.

Create a documentation plan from requirements analysis output. Dispatches the docs-planner agent. Invoked by the orchestrator.

Security and PII scan of documentation drafts before publication. Runs the deterministic PII scanner, then applies the docs-review-security checklist for agent-based analysis. Iteration logic is owned by the orchestrator, not this skill.

Assess JIRA ticket readiness for the docs-orchestrator workflow. Checks description quality (via LLM), PR/source linkage, metadata completeness, and relationship context (2-level graph traversal). Outputs structured JSON verdict with actionable gaps. Use when you want to check if a JIRA ticket has enough information before starting a docs workflow.

Style guide compliance review of documentation drafts. Dispatches the docs-reviewer agent with Vale linting and 18+ style guide review skills.

Create a linked JIRA ticket for documentation work. No agent dispatch. Uses direct JIRA REST API calls via a shell script. Checks for existing links, handles public/private project visibility, converts markdown to JIRA wiki markup.

Commit, push, and create a merge request (GitLab) or pull request (GitHub) for documentation changes. Creates a feature branch if the repo is on main/master. Replaces docs-workflow-prepare-branch, docs-workflow-commit, and docs-workflow-create-mr.

Check whether a JIRA query returns tickets ready for the docs workflow. Queries JIRA via jira_reader.py, filters out tickets that already have a workflow progress file or a "docs-workflow-started" label, and outputs a JSON list of actionable ticket IDs. Designed as the entry point for cron-triggered or CI-triggered docs-orchestrator runs.

Run PR/MR analysis for the docs orchestrator workflow. Dispatches a subagent to run understand-pull-request, keeping the heavy orchestration out of the main context. Produces a structured PR-ANALYSIS.md. Conditional on has_pr — skipped when no PR URL is available.

Interactive guided setup for the docs workflow. Only invoke this skill when the user explicitly requests docs-workflow-start (e.g., /docs-workflow-start). Do NOT invoke this skill when the user requests docs-orchestrator — that skill runs directly. When invoked with no CLI switches, uses AskUserQuestion to gather configuration. Supports full workflow, individual steps with auto-resolved prerequisites, and resuming previous runs. When switches are provided, passes through directly to docs-orchestrator.

Scan documentation for sensitive data before publication — real IP addresses, credentials, internal hostnames, email addresses, and MAC addresses. Use this skill when asked to check for PII, security issues, customer-sensitive data, or before publishing documentation. Runs a deterministic regex scanner first, then applies agent judgment for patterns regex cannot catch.

Read and analyze JIRA issues from Red Hat Issue Tracker. Use this skill to fetch issue details, search issues, extract comments and discussions, categorize issues (bugs, CVEs, features, stories), analyze custom fields (release notes, fix versions), retrieve Git links, traverse ticket graphs (parent, children, siblings, links), and generate summaries. This skill is read-only and cannot modify JIRA issues. Requires jira and ratelimit Python packages.

Download HTML from websites and extract article content, removing HTML bloat. Specifically designed to extract content from <article> tags with aria-live="polite" attribute. Outputs clean, readable content for documentation sites like Red Hat docs.

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.

Multi-agent style guide and modular docs review with confidence scoring. Supports local branch review, PR/MR review with optional inline comment posting, and fix mode. MUST BE USED when the user asks for style guide compliance review, modular docs structure review, content quality checks, or wants to review documentation for formatting and language issues.

Technical accuracy review and code-aware validation with confidence scoring. Supports local branch review, PR/MR review with optional inline comment posting. MUST BE USED when the user asks to validate documentation against code, check technical accuracy, verify commands/APIs/configs in docs match source code, or run a technical review. Also use when the user provides a --code URL or mentions code-aware review.

Update and modify JIRA issues on Red Hat Issue Tracker. Use this skill to push release notes, update custom fields (release note content, status), manage labels (add/remove), and modify issue properties. This skill performs write operations and will prompt for user approval before making changes. Requires jira and ratelimit Python packages. Only use when explicitly asked to update or modify JIRA issues.

Analyze a codebase for engineer onboarding. Detects language, maps modules, analyzes each module in parallel, discovers cross-module relationships, and produces an ONBOARDING.md guide.

Answer questions about a previously analyzed codebase. Reads learn-code output and dispatches an agent that can also Read/Grep the actual source code to provide file:line-grounded answers.

Extract distinct article URLs from Red Hat documentation table of contents pages. Parse the TOC navigation to find all separate documentation articles. Useful for crawling and processing multi-page Red Hat documentation.

Check known issue status for a release version. Shows which known issues are still open (document in Known Issues) and which are resolved (move to Fixed Issues or remove). Use when asked to check known issues, audit release notes known issues, or find resolved known issues for a version.

Analyze a pull request or merge request. Fetches PR metadata via git-pr-reader, identifies affected modules, analyzes changes in context, and produces a PR-ANALYSIS.md document with a brief repo overview and detailed change analysis.

Run Vale linting to check for style guide violations. Supports Markdown, AsciiDoc, reStructuredText, HTML, XML, and source code comments. Use this skill when asked to lint, check style, or validate documentation.

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."

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.

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.

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.

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.

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.

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.

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.