docs(skills): split documentation workflows

.agents/skills/switchyard-docs-draft/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: switchyard-docs-draft
+description: Draft net-new Switchyard documentation from repository evidence. Use when creating a new guide, tutorial, explanation, or reference page under docs/; not for polishing an existing page or reviewing examples only.
+---
+
+# Draft Switchyard Documentation
+
+Adapted from NVIDIA Tech Docs Skill Library's `doc-draft` workflow (Apache-2.0).
+
+Read `AGENTS.md` and `docs/AGENTS.md` completely before drafting.
+
+## Workflow
+
+1. Restate the requested document and identify its likely audience and Diataxis type: tutorial,
+   how-to, explanation, or reference.
+2. Inspect the current documentation tree and `mkdocs.yml`. Decide whether to update an existing
+   page or create a public or internal page.
+3. Enumerate evidence sources before writing:
+   - public source and configuration;
+   - CLI definitions or generated help;
+   - request and response schemas;
+   - tests and examples;
+   - related documentation.
+4. Build a claim list. Include only claims supported by the inspected artifacts. Keep uncertain
+   claims out of published text and report them as maintainer questions.
+5. Draft the shortest document that lets the target reader complete or understand the task.
+6. Derive code examples from verified APIs and behavior. An example may compose public APIs into a
+   new runnable snippet, but every symbol, argument, flag, field, and default must be verified.
+7. Integrate the page into `mkdocs.yml` as required by `docs/AGENTS.md`.
+8. Run the strict docs build and report the evidence used, unresolved questions, and validation.
+
+## Drafting Rules
+
+- Front-load the outcome and prerequisites.
+- Keep tutorials sequential, how-to guides task-oriented, explanations conceptual, and references
+  exhaustive within their declared scope.
+- Prefer one complete example over several fragments.
+- Label intentionally abbreviated examples or pseudocode.
+- Do not publish speculative recommendations, performance claims, or unverified compatibility.
+- Do not put source `file:line` annotations into reader-facing prose.
+
+## Handoff
+
+Report the created or updated paths, document type, principal evidence sources, unresolved questions,
+and exact validation commands. Do not claim a live provider example was tested unless it was.

.agents/skills/switchyard-docs-example-audit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: switchyard-docs-example-audit
+description: Audit Switchyard documentation examples against source code and schemas. Use when reviewing Python imports and call shapes, CLI commands and defaults, profile configuration, environment variables, or HTTP request and response examples.
+---
+
+# Audit Switchyard Documentation Examples
+
+Adapted from NVIDIA Tech Docs Skill Library's `doc-code-example-audit` workflow (Apache-2.0).
+
+Read `AGENTS.md` and `docs/AGENTS.md` completely. This is read-only unless the user also asks to fix
+the findings.
+
+## Audit Checklist
+
+### Python
+
+- Verify imports use the canonical public package.
+- Verify every referenced symbol exists and is publicly exported.
+- Check constructor and method signatures against the current checkout.
+- Mark illustrative types and pseudocode explicitly.
+
+### CLI
+
+- Read the owning parser definition or generated help.
+- Check subcommand nesting, flag spelling, aliases, defaults, deprecations, and mutual exclusions.
+- Confirm paths are interpreted as documented.
+
+### Configuration
+
+- Find the owning config model and loader.
+- Check field names, nesting, accepted values, required fields, and defaults.
+- Search other documentation for contradictory descriptions of the same field.
+
+### HTTP and JSON
+
+- Find the owning schema, wire type, translator, endpoint, and representative tests.
+- Check field names, nesting, value types, and streaming versus non-streaming shape.
+- Do not accept an example merely because it resembles an upstream provider format.
+
+### Environment and Providers
+
+- Confirm each environment variable is consumed by source.
+- Verify precedence between explicit arguments, saved configuration, and environment fallbacks.
+- Flag examples that imply credentials or live provider behavior without saying so.
+
+## Findings
+
+Report only verified mismatches. For each finding, include the documentation location, observed text,
+authoritative source, user impact, and minimal correction. Separate confirmed defects from questions.
+Say clearly when no material accuracy issues are found.

.agents/skills/switchyard-docs-novice-review/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: switchyard-docs-novice-review
+description: Review Switchyard documentation as a technically capable user who is new to the project. Use to find missing prerequisites, unexplained project terminology, incomplete setup steps, unclear success signals, and onboarding dead ends.
+---
+
+# Review Switchyard Documentation as a Newcomer
+
+Adapted from NVIDIA Tech Docs Skill Library's `doc-persona-novice` workflow (Apache-2.0).
+
+Read `AGENTS.md` and `docs/AGENTS.md` completely. Review without editing unless the user also asks
+for fixes.
+
+Assume solid general software knowledge but no prior Switchyard knowledge. Understand APIs, CLIs,
+LLMs, YAML, Git, and terminals; do not manufacture confusion about standard concepts.
+
+## Review Lenses
+
+1. **First contact:** Can the reader explain what the documented feature does, why it exists, and
+   when to use it?
+2. **Prerequisites:** Are required packages, credentials, services, configuration, and platform
+   constraints stated before the first step?
+3. **Sequence:** Can the reader move from one step to the next without an implied action?
+4. **Success signals:** Does each important operation explain how to tell that it worked?
+5. **Recovery:** Are likely failures actionable or linked to the right troubleshooting material?
+6. **Project terminology:** Are Switchyard-specific terms defined at first use or linked clearly?
+7. **Navigation:** Can the reader find the next relevant task without understanding the repository
+   layout?
+
+## Findings
+
+For each material issue, quote the smallest relevant passage, state where a capable newcomer gets
+stuck, and propose the smallest correction. Distinguish project-specific jargon from normal
+engineering terminology. End with an onboarding-readiness assessment and say clearly when no major
+gaps are present.

.agents/skills/switchyard-docs-polish/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: switchyard-docs-polish
+description: Improve an existing Switchyard documentation page without changing its technical scope. Use when asked to polish, tighten, clarify, reorganize, or improve the readability of established Markdown content under docs/.
+---
+
+# Polish Switchyard Documentation
+
+Adapted from NVIDIA Tech Docs Skill Library's `doc-polish` workflow (Apache-2.0).
+
+Read `AGENTS.md` and `docs/AGENTS.md` completely before editing. Use this workflow only when the
+page's foundation is sound; route missing or questionable technical content through
+`switchyard-docs-example-audit` or a source-backed drafting pass first.
+
+## Workflow
+
+1. Identify the page's audience, purpose, and Diataxis type.
+2. Preserve its technical scope and collect a small before-state assessment:
+   - Is the outcome visible early?
+   - Is the page scannable?
+   - Are prerequisites and next steps easy to find?
+   - Are examples complete enough for the intended audience?
+3. Improve signal-to-noise. Remove repetition, filler, throat-clearing, and headings that do not
+   help navigation. Replace vague claims with concrete language without inventing facts.
+4. Align the structure with the page type. Do not turn a reference into a tutorial or mix a long
+   conceptual explanation into a task procedure.
+5. Apply progressive disclosure: essential path first, optional detail later, advanced material
+   behind a clear heading or supported disclosure element.
+6. Improve headings, paragraphs, lists, terminology, and links. Use MkDocs features already enabled
+   in `mkdocs.yml`; do not introduce syntax from another documentation framework.
+7. Review the diff and remove changes that are merely stylistic churn.
+8. Run the strict docs build.
+
+## Boundaries
+
+- Do not alter documented behavior unless source evidence proves the old text wrong.
+- Do not add features, examples, recommendations, or promises to make a page feel complete.
+- Do not replace precise technical language with marketing language.
+- Do not restructure neighboring pages unless the user asked for broader information architecture.
+
+## Handoff
+
+Summarize the material improvements, call out any accuracy questions left untouched, and report the
+exact validation performed.

.agents/skills/switchyard-docs-pragmatist-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: switchyard-docs-pragmatist-review
+description: Review Switchyard documentation for copy-paste usability and scannability from a busy developer's perspective. Use to find incomplete commands, non-runnable examples, buried prerequisites, missing expected output, and avoidable task friction.
+---
+
+# Review Switchyard Documentation for Task Usability
+
+Adapted from NVIDIA Tech Docs Skill Library's `doc-persona-pragmatist` workflow (Apache-2.0).
+
+Read `AGENTS.md` and `docs/AGENTS.md` completely. Review without editing unless the user also asks
+for fixes.
+
+Assume an experienced engineer with a deadline who scans headings and examples before reading long
+explanations.
+
+## Review Lenses
+
+1. **Copy-paste path:** Check whether commands and code blocks are complete in their stated context.
+2. **Setup:** Find missing imports, variables, files, credentials, working-directory assumptions,
+   and prerequisite commands.
+3. **Scannability:** Confirm the primary command or example appears before optional detail and under
+   a heading a task-oriented reader would recognize.
+4. **Expected result:** Check whether the reader can tell that each key step succeeded.
+5. **Failure path:** Check whether common errors have an immediate fix or a precise link.
+6. **End-to-end completeness:** Prefer one complete runnable path over fragments that require the
+   reader to assemble hidden context.
+
+Do not demand that every conceptual page become a quickstart. Judge the page against its declared
+purpose and audience.
+
+## Findings
+
+For each material issue, identify the location, explain the concrete failure or friction, and propose
+the smallest fix. Separate confirmed runnability failures from untested concerns. End with an
+estimated time-to-first-success assessment and say clearly when the page is ready for a busy reader.