Docs Workflow Writing

Documentation Writing Step

Step skill for the docs-orchestrator pipeline. Follows the step skill contract: run script → dispatch agent → verify output.

Execution

1. Run the script

Run the build script to parse arguments, validate inputs, determine mode, and create output directories:

bash ${CLAUDE_SKILL_DIR}/scripts/build_writing_args.sh 

Pass through the full args string. The script emits JSON on stdout:

{
  "mode":                "update-in-place | draft | fix",
  "ticket":              "PROJ-123",
  "format":              "adoc | mkdocs",
  "input_file":          "/planning/plan.md",
  "evidence_file":       "/code-evidence/evidence.json | null",
  "has_evidence":        true | false,
  "evidence_status":     "/scope-req-audit/evidence-status.json | null",
  "has_evidence_status": true | false,
  "output_dir":          "/writing",
  "output_file":         "/writing/_index.md",
  "docs_repo_path":      " | null",
  "source_repo_path":    " | null",
  "fix_from":            " | null",
  "verify_output":       true | false
}

If the script exits non-zero, stop and report the error from stderr.

2. Dispatch the docs-writer agent

You MUST use the Agent tool to invoke the docs-writer subagent. Do NOT read the agent's markdown file or attempt to perform the agent's work yourself — the agent has a specialized system prompt and must run as an isolated subagent.

Select the prompt based on mode and format from the JSON output. In every prompt below, substitute the `, , , , , , and ` placeholders with the corresponding values from the script's JSON.

Agent tool parameters for all modes:

• subagent_type: docs-writer
• description: use the value described under each mode below

---

Mode: update-in-place, format: adoc

Description: Write adoc documentation for

Prompt:

> Write complete AsciiDoc documentation based on the documentation plan for ticket `. > > Read the plan from: > > **[Include only if HAS_EVIDENCE=true]** Code evidence is available at . Read it and use the sourceresults for accurate function signatures, parameter types, and code examples. Use contextresults for narrative context, installation steps, and architectural patterns. Prefer evidence over assumptions — if the evidence contradicts the plan, follow the evidence. > > **[Include only if HAS_EVIDENCE_STATUS=true]** Evidence classifications are available at . Read it and apply these rules per requirement: > - **Grounded** requirements have strong code evidence — write with full technical detail > - **Partial** requirements have weak or ambiguous evidence — write the content but mark unverified technical details (API names, parameter values, configuration keys) with [NEEDS VERIFICATION] > - **Absent** requirements have no code evidence — if they appear in the plan, skip them and note the omission in the manifest. Do NOT fabricate API signatures, SDK imports, CRD schemas, or configuration examples for absent requirements > > **[Include only if SOURCE_REPO is not null]** Source code repository is available at . You may read specific source files for additional detail when the code evidence does not contain sufficient information for a section. Use this to verify function signatures, check parameter types, or find code examples — do not browse the entire repo. > > **IMPORTANT**: Write COMPLETE .adoc files, not summaries or outlines. > > **Placement mode: UPDATE-IN-PLACE** > > [If docsrepopath is not null: "The target repository is at . Explore **that directory** for framework detection and write files there."] > > Place files directly in the repository following existing conventions. Before writing any files: > 1. Detect the repository's documentation build framework (Antora, ccutil, Sphinx, etc.) > 2. Analyze existing file naming conventions, directory layout, include patterns, and nav/TOC structure > 3. 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 listing **all files written and modified** with **absolute paths**. The manifest must include every intentional change — both new files created and existing files modified (e.g., nav/TOC updates). > > [If docsrepopath is not null: "Record Target repo: ` in the manifest header."]

---

Mode: update-in-place, format: mkdocs

Description: Write mkdocs documentation for

Prompt:

> Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket `. > > Read the plan from: > > **[Include only if HAS_EVIDENCE=true]** Code evidence is available at . Read it and use the sourceresults for accurate function signatures, parameter types, and code examples. Use contextresults for narrative context, installation steps, and architectural patterns. Prefer evidence over assumptions — if the evidence contradicts the plan, follow the evidence. > > **[Include only if HAS_EVIDENCE_STATUS=true]** Evidence classifications are available at . Read it and apply these rules per requirement: > - **Grounded** requirements have strong code evidence — write with full technical detail > - **Partial** requirements have weak or ambiguous evidence — write the content but mark unverified technical details (API names, parameter values, configuration keys) with [NEEDS VERIFICATION] > - **Absent** requirements have no code evidence — if they appear in the plan, skip them and note the omission in the manifest. Do NOT fabricate API signatures, SDK imports, CRD schemas, or configuration examples for absent requirements > > **[Include only if SOURCE_REPO is not null]** Source code repository is available at . You may read specific source files for additional detail when the code evidence does not contain sufficient information for a section. Use this to verify function signatures, check parameter types, or find code examples — do not browse the entire repo. > > **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** > > [If docsrepopath is not null: "The target repository is at . Explore **that directory** for framework detection and write files there."] > > Place files directly in the repository following existing conventions. Before writing any files: > 1. Detect the repository's documentation build framework (MkDocs, Docusaurus, Hugo, etc.) > 2. Analyze existing file naming conventions, directory layout, and nav structure > 3. 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.yml nav section or equivalent as needed, following existing patterns. > > Create a manifest at listing **all files written and modified** with **absolute paths**. The manifest must include every intentional change — both new files created and existing files modified (e.g., mkdocs.yml nav updates). > > [If docsrepopath is not null: "Record Target repo: ` in the manifest header."]

---

Mode: draft, format: adoc

Description: Write adoc documentation for

Prompt:

> Write complete AsciiDoc documentation based on the documentation plan for ticket `. > > Read the plan from: > > **[Include only if HAS_EVIDENCE=true]** Code evidence is available at . Read it and use the sourceresults for accurate function signatures, parameter types, and code examples. Use contextresults for narrative context, installation steps, and architectural patterns. Prefer evidence over assumptions — if the evidence contradicts the plan, follow the evidence. > > **[Include only if HAS_EVIDENCE_STATUS=true]** Evidence classifications are available at . Read it and apply these rules per requirement: > - **Grounded** requirements have strong code evidence — write with full technical detail > - **Partial** requirements have weak or ambiguous evidence — write the content but mark unverified technical details (API names, parameter values, configuration keys) with [NEEDS VERIFICATION] > - **Absent** requirements have no code evidence — if they appear in the plan, skip them and note the omission in the manifest. Do NOT fabricate API signatures, SDK imports, CRD schemas, or configuration examples for absent requirements > > **[Include only if SOURCE_REPO is not null]** Source code repository is available at . You may read specific source files for additional detail when the code evidence does not contain sufficient information for a section. Use this to verify function signatures, check parameter types, or find code examples — do not browse the entire repo. > > **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: > ` > / > ├── _index.md # Index of all modules > ├── assembly_.adoc # Assembly files at root > └── modules/ # All module files > ├── .adoc > ├── .adoc > └── .adoc > ` > > Save modules to: /modules/ > Save assemblies to: / > Create index at: `

---

Mode: draft, format: mkdocs

Description: Write mkdocs documentation for

Prompt:

> Write complete Material for MkDocs Markdown documentation based on the documentation plan for ticket `. > > Read the plan from: > > **[Include only if HAS_EVIDENCE=true]** Code evidence is available at . Read it and use the sourceresults for accurate function signatures, parameter types, and code examples. Use contextresults for narrative context, installation steps, and architectural patterns. Prefer evidence over assumptions — if the evidence contradicts the plan, follow the evidence. > > **[Include only if HAS_EVIDENCE_STATUS=true]** Evidence classifications are available at . Read it and apply these rules per requirement: > - **Grounded** requirements have strong code evidence — write with full technical detail > - **Partial** requirements have weak or ambiguous evidence — write the content but mark unverified technical details (API names, parameter values, configuration keys) with [NEEDS VERIFICATION] > - **Absent** requirements have no code evidence — if they appear in the plan, skip them and note the omission in the manifest. Do NOT fabricate API signatures, SDK imports, CRD schemas, or configuration examples for absent requirements > > **[Include only if SOURCE_REPO is not null]** Source code repository is available at . You may read specific source files for additional detail when the code evidence does not contain sufficient information for a section. Use this to verify function signatures, check parameter types, or find code examples — do not browse the entire repo. > > **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: > ` > / > ├── _index.md # Index of all pages > ├── mkdocs-nav.yml # Suggested nav tree fragment > └── docs/ # All page files > ├── .md > ├── .md > └── .md > ` > > Save pages to: /docs/ > Create nav fragment at: /mkdocs-nav.yml > Create index at: `

---

Mode: fix

Description: Fix documentation for

Prompt:

> Apply fixes to documentation drafts based on technical review feedback for ticket `. > > Read the review report from: > Drafts location: /` > > For each issue flagged in the review: > 1. If the fix is clear and unambiguous, apply it directly > 2. If the issue requires broader context or judgment, skip it > 3. 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.

---

3. Verify output

If verify_output is true in the script's JSON output, check that output_file exists.

If verify_output is false (fix mode), no verification is needed — files are edited in place.

4. Write step-result.json

Skip this step if mode is "fix" (fixes edit files in place — no new manifest to parse).

Read the manifest at ` (_index.md). Extract every absolute file path from the table rows. These become the files` array.

Write the sidecar to /step-result.json using the mode and format values from the script's JSON output:

{
  "schema_version": 1,
  "step": "writing",
  "ticket": "",
  "completed_at": "",
  "files": [
    "/absolute/path/to/file1.adoc",
    "/absolute/path/to/file2.adoc"
  ],
  "mode": "",
  "format": ""
}

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhatt-rh
• Source: abhatt-rh/redhat-docs-agent-tools
• License: Apache-2.0
• Homepage: https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.