docs-writer
**WORKFLOW SKILL** — Maintains repository documentation accuracy and freshness across the docs site, agent files, and changelog. WHEN: "update docs", "doc gardening", "staleness check", "changelog entry", "repo explanation", "agent change docs", "skill change docs". DO NOT USE FOR: agent definitions (edit `.agent.md` directly), SKILL.md content authoring, site theme/build.
git clone --depth 1 https://github.com/jonathan-vella/apex /tmp/docs-writer && cp -r /tmp/docs-writer/.github/skills/docs-writer ~/.claude/skills/docs-writerSKILL.md
# docs-writer You are an expert technical writer with deep knowledge of the APEX repository. You understand how agents, skills, instructions, templates, and artifacts connect. You maintain all user-facing documentation to be accurate, current, and consistent. ## When to Use This Skill | Trigger Phrase | Workflow | | ------------------------------ | ----------------------------------- | | "Update the docs" | Update existing documentation | | "Add docs for new agent/skill" | Add entity documentation | | "Check docs for staleness" | Freshness audit with auto-fix | | "Explain how this repo works" | Architectural Q&A | | "Proofread the docs" | Language, tone, and accuracy review | | "Generate a changelog entry" | Changelog from git history | ## Prerequisites None — all tools and references are workspace-local. ## Scope ### In Scope All markdown documentation **except** `agent-output/**/*.md`: - `site/src/content/docs/` — published user-facing docs (quickstart, workflow, troubleshooting, etc.) - `tools/tests/exec-plans/tech-debt-tracker.md` — tech debt inventory - `README.md` — repo root README - `CONTRIBUTING.md` — contribution guidelines - `CHANGELOG.md` — release history - `QUALITY_SCORE.md` — project health grades - `.github/instructions/docs.instructions.md` — site docs standards ### Out of Scope (Has Own Validators) | Path | Governed By | | ------------------------------------------- | ---------------------------------------------- | | `agent-output/**/*.md` | `azure-artifacts.instructions.md` + validators | | `.github/agents/*.agent.md` | `agent-authoring.instructions.md` | | `.github/skills/azure-artifacts/templates/` | Read-only reference (do not modify) | | `**/*.bicep` | `iac-bicep-best-practices.instructions.md` | ## Rules - **Out of scope, always** — `agent-output/**/*.md` (governed by `azure-artifacts.instructions.md`), `.github/agents/*.agent.md` (governed by `agent-authoring.instructions.md`), `**/*.bicep` (governed by `iac-bicep-best-practices.instructions.md`), `azure-artifacts/templates/` (read-only) - **Single H1 rule** — the title is the only H1; everything else is H2 or deeper - **120-char line limit** — CI enforces this on docs and instruction files - **Version source of truth** is `VERSION.md`; never hard-code version numbers in prose - **No hard-coded counts** — use descriptive language for entity counts (per `no-hardcoded-counts.instructions.md`); `count-manifest.json` is the source of truth - **Verify links** — all relative links must resolve to existing files; run `npm run lint:links` before committing - **Run validators** — `npm run lint:md` for style, `npm run lint:links` for link integrity - **Match adjacent patterns** when adding entries to existing tables (column format, emoji, description style) ## Step-by-Step Workflows The skill exposes seven workflows. Full per-step procedure for all seven lives in [`references/extended-workflows.md`](references/extended-workflows.md); the SKILL.md keeps a one-line summary so the agent knows which one to load. | # | Workflow | Trigger | Reference | | --: | --------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | 1 | Update Existing Documentation | "Update the docs for X" | [`extended-workflows.md`](references/extended-workflows.md) | | 2 | Add Documentation for New Entity | New agent/skill added to the repo | [`extended-workflows.md`](references/extended-workflows.md) | | 3 | Freshness Audit (Staleness Check) | "Audit docs for staleness" | [`freshness-checklist.md`](references/freshness-checklist.md) + [`extended-workflows.md`](references/extended-workflows.md) | | 4 | Explain the Repo Architecture | "How do agents connect to skills?" | [`repo-architecture.md`](references/repo-architecture.md) + [`extended-workflows.md`](references/extended-workflows.md) | | 5 | Generate Changelog Entry | Pre-release / `chore: changelog` | [`extended-workflows.md`](references/extended-workflows.md) | | 6 | Proofread Documentation | "Proofread the contributing guide" | [`extended-workflows.md`](references/extended-workflows.md) | | 7 | Process Freshness Issues | `docs-freshness` GitHub issue label | [`extended-workflows.md`](references/extended-workflows.md) | ## Guardrails - **Never modify** files in `agent-output/`, `.github/agents/`, or `.github/skills/azure-artifacts/templates/` - **Always read** the latest file version before editing - **Always verify** line length ≤ 120 characters after edits - **Preserve** existing Mermaid diagram theme directives - **Use** `VERSION.md` as the single source of truth for version numbers ## Troubleshooting | Issue | Solution | | ------------------------- | --------------------------------------------------------------- | | Lint fails on line length | Break lines at 120 chars after punctuation | | Link validation fails | Check relative paths resolve; use standard markdown link format | | Versi
Guidance for instrumenting webapps with Azure Application Insights. Provides telemetry patterns, SDK setup, and configuration references. WHEN: how to instrument app, App Insights SDK, telemetry patterns, what is App Insights, Application Insights guidance, instrumentation examples, APM best practices.
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway.
ROUTING SKILL — delegates to specialized diagram skills. USE FOR: any diagram request when the caller does not know which tool to use. Routes to drawio, python-diagrams, or mermaid based on diagram type.
Build and deploy GitHub Copilot SDK apps to Azure. WHEN: build copilot app, create copilot app, copilot SDK, @github/copilot-sdk, scaffold copilot project, copilot-powered app, deploy copilot app, host on azure, azure model, BYOM, bring your own model, use my own model, azure openai model, DefaultAzureCredential, self-hosted model, copilot SDK service, chat app with copilot, copilot-sdk-service template, azd init copilot, CopilotClient, createSession, sendAndWait, GitHub Models API.
Troubleshoot and resolve issues with Azure Messaging SDKs for Event Hubs and Service Bus. Covers connection failures, authentication errors, message processing issues, and SDK configuration problems. WHEN: event hub SDK error, service bus SDK issue, messaging connection failure, AMQP error, event processor host issue, message lock lost, send timeout, receiver disconnected, SDK troubleshooting, azure messaging SDK, event hub consumer, service bus queue issue, topic subscription error, enable logging event hub, service bus logging, eventhub python, servicebus java, eventhub javascript, servicebus dotnet, event hub checkpoint, event hub not receiving messages, service bus dead letter.
Authoritative reference for VS Code Copilot customization mechanisms: instructions, prompt files, custom agents, agent skills, MCP servers, hooks, and plugins. Use when deciding which customization type to use, creating new .instructions.md/.prompt.md/.agent.md/SKILL.md/mcp.json files from scratch, or debugging why a customization is not loading. DO NOT USE FOR: routine file edits where the format is already known.
Provides canonical entity counts from count-manifest.json. Use when agents need to reference how many agents, skills, instructions, or validators exist. Prevents hard-coded counts. WHEN: agent count, skill count, how many agents, how many skills, entity inventory, project statistics.