From docs-tools
Writes AsciiDoc or MkDocs documentation from a JIRA ticket plan. Dispatches docs-writer agent with update-in-place, draft staging, or fix-from-review modes.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin docs-toolsThis skill is limited to using the following tools:
Step skill for the docs-orchestrator pipeline. Follows the step skill contract: **parse args → dispatch agent → write output**.
Orchestrates documentation workflows from YAML step lists, running skills sequentially with progress state, iterations, confirmations, and JIRA/PR integration.
Manages MkDocs sites and standalone markdown files: initialize, generate, update docs, create change summaries. Triggers for 'create docs', 'write README', 'changelog' requests.
Generates and maintains technical documentation in modes: README, runbook, API, onboarding using audience-appropriate structured writing principles from code and draft context.
Share bugs, ideas, or general feedback.
Step skill for the docs-orchestrator pipeline. Follows the step skill contract: parse args → dispatch agent → write output.
Supports three modes:
--draft): Write files to a staging area under <base-path>/writing/. No framework detection, no repo modifications.--fix-from): Apply targeted corrections from a technical review.$1 — JIRA ticket ID (required)--base-path <path> — Base output path (e.g., .claude/docs/proj-123)--format <adoc|mkdocs> — Output format (default: adoc)--draft — Use DRAFT placement mode (staging area) instead of UPDATE-IN-PLACE$1 — JIRA ticket ID (required)--base-path <path> — Base output path--fix-from <path> — Technical review output file (triggers fix mode)<base-path>/planning/plan.md
UPDATE-IN-PLACE mode (default):
Files are written directly to their correct repo locations. A manifest is created at:
<base-path>/writing/_index.md
Draft mode (--draft):
<base-path>/writing/
_index.md
assembly_*.adoc (AsciiDoc mode)
modules/*.adoc (AsciiDoc mode)
mkdocs-nav.yml (MkDocs mode)
docs/*.md (MkDocs mode)
Extract the ticket ID, --base-path, --format, and --draft from the args string.
If --fix-from is present, operate in fix mode. Otherwise, check for --draft to determine placement mode.
Set the paths:
INPUT_FILE="${BASE_PATH}/planning/plan.md"
OUTPUT_DIR="${BASE_PATH}/writing"
OUTPUT_FILE="${OUTPUT_DIR}/_index.md"
mkdir -p "$OUTPUT_DIR"
--draft)Agent tool parameters:
subagent_type: docs-writerdescription: Write <format> documentation for <TICKET>Prompt (AsciiDoc):
Write complete AsciiDoc documentation based on the documentation plan for ticket
<TICKET>.Read the plan from:
<INPUT_FILE>IMPORTANT: Write COMPLETE .adoc files, not summaries or outlines.
Placement mode: UPDATE-IN-PLACE
Place files directly in the repository following existing conventions. Before writing any files:
- Detect the repository's documentation build framework (Antora, ccutil, Sphinx, etc.)
- Analyze existing file naming conventions, directory layout, include patterns, and nav/TOC structure
- Determine the correct target path for each module based on the detected framework and conventions
Write modules and assemblies directly to their correct repo locations. Update navigation/TOC files as needed, following existing patterns.
Create a manifest at
<OUTPUT_FILE>listing all files written and their repo locations.
Prompt (MkDocs):
Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket
<TICKET>.Read the plan from:
<INPUT_FILE>IMPORTANT: Write COMPLETE .md files with YAML frontmatter (title, description). Use Material for MkDocs conventions: admonitions, content tabs, code blocks with titles, heading hierarchy starting at
# h1.Placement mode: UPDATE-IN-PLACE
Place files directly in the repository following existing conventions. Before writing any files:
- Detect the repository's documentation build framework (MkDocs, Docusaurus, Hugo, etc.)
- Analyze existing file naming conventions, directory layout, and nav structure
- Determine the correct target path for each page based on the detected framework and conventions
Write pages directly to their correct repo locations. Update
mkdocs.ymlnav section or equivalent as needed, following existing patterns.Create a manifest at
<OUTPUT_FILE>listing all files written and their repo locations.
--draft)Agent tool parameters:
subagent_type: docs-writerdescription: Write <format> documentation for <TICKET>Prompt (AsciiDoc, draft):
Write complete AsciiDoc documentation based on the documentation plan for ticket
<TICKET>.Read the plan from:
<INPUT_FILE>IMPORTANT: Write COMPLETE .adoc files, not summaries or outlines.
Placement mode: DRAFT (staging area)
Save files to the staging area. Do not modify any existing repository files.
Output folder structure:
<OUTPUT_DIR>/ ├── _index.md # Index of all modules ├── assembly_<name>.adoc # Assembly files at root └── modules/ # All module files ├── <concept-name>.adoc ├── <procedure-name>.adoc └── <reference-name>.adocSave modules to:
<OUTPUT_DIR>/modules/Save assemblies to:<OUTPUT_DIR>/Create index at:<OUTPUT_FILE>
Prompt (MkDocs, draft):
Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket
<TICKET>.Read the plan from:
<INPUT_FILE>IMPORTANT: Write COMPLETE .md files with YAML frontmatter (title, description). Use Material for MkDocs conventions: admonitions, content tabs, code blocks with titles, heading hierarchy starting at
# h1.Placement mode: DRAFT (staging area)
Save files to the staging area. Do not modify any existing repository files.
Output folder structure:
<OUTPUT_DIR>/ ├── _index.md # Index of all pages ├── mkdocs-nav.yml # Suggested nav tree fragment └── docs/ # All page files ├── <concept-name>.md ├── <procedure-name>.md └── <reference-name>.mdSave pages to:
<OUTPUT_DIR>/docs/Create nav fragment at:<OUTPUT_DIR>/mkdocs-nav.ymlCreate index at:<OUTPUT_FILE>
When invoked with --fix-from, the skill applies targeted corrections to existing drafts.
Agent tool parameters:
subagent_type: docs-writerdescription: Fix documentation for <TICKET>Prompt:
Apply fixes to documentation drafts based on technical review feedback for ticket
<TICKET>.Read the review report from:
<FIX_FROM_PATH>Drafts location:<OUTPUT_DIR>/For each issue flagged in the review:
- If the fix is clear and unambiguous, apply it directly
- If the issue requires broader context or judgment, skip it
- Do NOT rewrite content that was not flagged
Edit files in place. Do NOT create copies or new files.
In fix mode, the skill does not create new modules or restructure content.
Normal mode (both UPDATE-IN-PLACE and DRAFT): Check that _index.md exists at <OUTPUT_FILE>.
Fix mode: No output verification needed — files are edited in place.