Docs workflow writing

Skill opendatahub-io/docs-skills/skills/docs-workflow-writing

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.From its SKILL.md

Install

npx -y skills add opendatahub-io/docs-skills --skill docs-workflow-writing

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.5 KB, as published. Nobody here has run it

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 <args>

Pass through the args unquoted so each flag and value is a separate shell word. Do NOT wrap the entire args string in quotes — the script uses positional argument parsing and each --flag value pair must be a separate argument. The script emits JSON on stdout:

{
  "mode":                "update-in-place | draft | fix",
  "ticket":              "PROJ-123",
  "format":              "adoc | mkdocs",
  "input_file":          "<base-path>/planning/plan.md",
  "code_analysis_dir":   "<base-path>/code-analysis/ | null",
  "has_code_analysis":   true | false,
  "pr_analysis_dir":     "<base-path>/pr-analysis/ | null",
  "has_pr_analysis":     true | false,
  "output_dir":          "<base-path>/writing",
  "output_file":         "<base-path>/writing/_index.md",
  "docs_repo_path":      "<path> | null",
  "source_repo_path":    "<path> | null",
  "additional_repo_paths": ["<path>", ...],
  "additional_code_analysis_dirs": ["<path>", ...],
  "fix_from":            "<path> | 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. See agent prompts for the full prompt text for each combination.

`mode`	`format`	Description
`update-in-place`	`adoc`	`Write adoc documentation for <TICKET>`
`update-in-place`	`mkdocs`	`Write mkdocs documentation for <TICKET>`
`draft`	`adoc`	`Write adoc documentation for <TICKET>`
`draft`	`mkdocs`	`Write mkdocs documentation for <TICKET>`
`fix`	(any)	`Fix documentation for <TICKET>`

Agent tool parameters for all modes:

subagent_type: docs-skills:docs-writer
description: use the value from the Description column
run_in_background: false (the orchestrator must wait for the writer to finish before verifying output)

In every prompt, substitute the <TICKET>, <INPUT_FILE>, <OUTPUT_FILE>, <OUTPUT_DIR>, <DOCS_REPO_PATH>, <FIX_FROM>, <CODE_ANALYSIS_DIR>, <PR_ANALYSIS_DIR>, <SOURCE_REPO>, <ADDITIONAL_REPO_PATHS>, <ADDITIONAL_CODE_ANALYSIS_DIRS>, HAS_CODE_ANALYSIS, and HAS_PR_ANALYSIS placeholders with the corresponding values from the script's JSON.

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

Do not hand-author the sidecar — a hand-written sidecar drifts from the schema and uses an orchestrator-delayed timestamp instead of a real wall-clock one. Run the script, passing mode and format from the build script's JSON output:

python3 ${CLAUDE_SKILL_DIR}/scripts/write_step_result.py \
  --ticket "<TICKET>" \
  --manifest "<OUTPUT_FILE>" \
  --mode "<mode from script JSON>" \
  --format "<format from script JSON>" \
  --sidecar "<OUTPUT_DIR>/step-result.json"

The script parses absolute file paths from the manifest's table rows and writes the conformant step-result.json with a real wall-clock completed_at. If the script exits non-zero, fix the arguments and re-run; do not substitute a stub.