---

name: docs-site description: "Guide Astro/Starlight docs-site authoring, review, navigation, sourceLinks, snippets, and generated API docs work." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Docs site

Use this sub-skill for work on the Strands Agents Astro/Starlight documentation site, including page authoring, docs review, navigation, snippets, source links, and generated API reference workflows.

Start here

1. Read overview.md to map site concerns, content sources, and routing boundaries.
2. Read authoring.md before changing page content, snippets, tabs, frontmatter, or terminology.
3. Read workflows.md for review, build, API regeneration, route, and migration flows.
4. Read troubleshooting.md when validation or review fails.
5. Use docs-site-check.sh for focused site checks and generate-api-docs.sh for generated API reference refreshes.

Use this sub-skill for

• MDX frontmatter, page structure, content collections, Starlight components, and navigation.
• Language tabs, <Syntax>, snippet includes, TypeScript snippet scoping, relative links, and @api shorthand.
• sourceLinks maintenance when SDK files move or docs pages are backed by implementation files.
• Generated Python and TypeScript API docs regeneration; never hand-edit generated API output.
• Docs review, docs audit, docs planning, voice, terminology, and code-example verification.
• Site tests, snippet typechecks, route middleware, sidebar behavior, and build checks.

Route elsewhere

• Python SDK implementation details, Python API signatures, or Python tests: use python-sdk.
• TypeScript SDK implementation details, package exports, or Node/browser tests: use typescript-sdk.
• Docs-search MCP server runtime, search_docs, or fetch_doc: use mcp-server.

Guardrails

• Do not hand-edit generated API docs; regenerate and review the resulting diff.
• Keep sourceLinks current in the same change when source files move or rename.
• Use the canonical term for each SDK concept; do not vary wording for style.
• Verify code examples against current SDK source before handoff, and omit unverifiable code rather than guessing.
• Use <Syntax> for one inline language-specific identifier and <Tabs> for multi-line or structurally different examples.
• Keep MDX pages readable from search: clear page goal, coherent content type, and no unexplained internal process artifacts.

Fast path

1. Classify the task as authoring, review/audit, API regeneration, navigation/route maintenance, sourceLink repair, or troubleshooting.
2. Read the matching reference and choose the smallest check script mode that proves the affected surface.
3. If source files moved, update docs sourceLinks and verify API/source links before running broad site checks.
4. If snippets changed, run snippet typechecks and inspect rendered include boundaries.
5. Record skipped site build, API generation, or live-doc checks explicitly when dependencies or network access are unavailable.