Add verify-procedure skill

[kquinn1204]

Summary

Adds the verify-procedure skill to docs-tools. This skill executes AsciiDoc procedures against a live system to prove they work end-to-end — it is the "guided exercise tester" for documentation.

3 files changed, 1 commit. No changes to dita-tools or any other existing plugin.

---

What it does

This skill requires an active connection to the target system (oc login, SSH, etc.). It is not a review tool — for offline documentation review, use the technical-reviewer agent instead.

How it works

1. Parse the .adoc file to extract all [source,terminal], [source,bash], and [source,yaml] blocks, associating each with its numbered step
2. Execute the verify_proc.rb Ruby script against the file
3. Report pass/fail results per step with a final summary

What the Ruby script does (verify_proc.rb)

Capability	Details
Step extraction	Parses AsciiDoc numbered steps (. Step text) and associates each [source,yaml], [source,terminal], or [source,bash] block with its parent step
YAML validation	Parses every YAML block for syntax errors. For Kubernetes resources (apiVersion: detected), runs oc apply --dry-run=client or kubectl apply --dry-run=client (auto-detects which CLI is available)
Bash execution	Strips leading $ prompts, joins backslash-continued lines, executes each command, captures stdout/stderr/exit code. On failure, logs the error and continues to the next step
Smart skipping	Skips example output blocks (preceded by "Example output") and placeholder blocks (<placeholder>, ${VAR}, CHANGEME, REPLACE)
Best practices check	Scans for login/setup patterns across products (oc login, ssh, sudo, subscription-manager, dnf install, ansible-playbook, etc.) and warns about potential "magic steps" if none are found
Summary	Reports total executable steps, pass/fail counts, lists each failed step with its error, and flags if no verification step exists

Product support

The script is product-agnostic. It runs whatever commands are in the doc:

Product	What makes it work
OpenShift	oc commands execute, YAML dry-run via oc apply
RHEL	dnf, systemctl, nmcli etc. execute on the local machine
OpenStack	openstack CLI commands execute if installed and sourced
Ansible	ansible-playbook, ansible-navigator execute if installed

Example output

--- Starting Procedure Validation: nw-ptp-installing-operator-cli.adoc ---

[Step 1] Create a namespace for the PTP Operator
[VALID] YAML syntax for Step 1 is correct.
[VALID] Resource logic (dry-run via oc) passed for Step 1.

[Step 2] Create the Namespace CR
Executing: oc create -f ptp-namespace.yaml
[SUCCESS] Step 2 executed.

[Step 3] ...
[SKIP] Example output - not executed

============================================================
FINAL SUMMARY
============================================================
Total executable steps: 7
Passed: 6
Failed: 1

Failed steps:
  - Step 5: error: the server doesn't have a resource type "PtpConfig"
============================================================
✗ Some steps FAILED
============================================================

Relationship to technical-reviewer agent

	verify-procedure	technical-reviewer
Purpose	Execute commands on a live system	Review documentation for technical accuracy
Requires live system	Yes	No
Runs commands	Yes	No
Checks structure/prereqs	No (defers to technical-reviewer)	Yes
Output	Pass/fail per step	Review with issues and confidence score

---

Files changed

• plugins/docs-tools/skills/verify-procedure/SKILL.md — skill definition
• plugins/docs-tools/skills/verify-procedure/scripts/verify_proc.rb — Ruby execution script
• plugins/docs-tools/.claude-plugin/plugin.json — version bump 0.0.2 → 0.0.3

[aireilly]

Thanks for the PR Kevin. Note this duplicates a lot of existing functionality, and some of the skills are not suitable for this repo.

Suggest reviewing what's in the repo currently, and focusing the PR on net new skills and updates only.

[aireilly]

This is covered in https://github.com/redhat-documentation/redhat-docs-agent-tools/blob/main/plugins/dita-tools/reference/dita-rewrite-fixing-instructions.md#L14

[aireilly]

this is openshift specific, it's not a general skill.

[aireilly]

This seems to duplicate functionality from the technical-reviewer agent, and also I don't know what the verify_proc script actually does?

[kquinn1204]

I have updated the skill so it should apply across multiple products though have only tried with OCP can still decide not to add to repo up to you