| name | docs-writer |
| description | **WORKFLOW SKILL** — Maintains Markdown documentation accuracy and freshness across docs, root guides, and changelog. WHEN: "update docs", "doc gardening", "staleness check", "changelog entry", "repo explanation", "agent change docs", "skill change docs". |
| license | MIT |
| compatibility | Works with GitHub Copilot, VS Code, and any Agent Skills compatible tool; no external dependencies required. |
| metadata | {"author":"jonathan-vella","version":"1.0","category":"documentation"} |
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:
docs/ — vNext tutorials, how-to guides, explanations, references, migration, and project controlstools/tests/exec-plans/tech-debt-tracker.md — tech debt inventoryREADME.md — repo root READMECONTRIBUTING.md — contribution guidelinesCHANGELOG.md — release historycustomizations/.github/instructions/apex-documentation.instructions.md — consumer user-guide standards
Out of Scope (Has Own Validators)
| Path | Governed By |
|---|
agent-output/**/*.md | azure-artifacts.instructions.md + validators |
customizations/.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), customizations/.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 validate:docs for style, links, and freshness
- 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; the SKILL.md keeps a
one-line summary so the agent knows which one to load.
Guardrails
- Never modify files in
agent-output/, customizations/.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 |
| Version mismatch | Read VERSION.md and propagate to all docs |
| Count mismatch | List managed agents and .github/skills/ directories |
References
references/repo-architecture.md — Repo structure, entity inventoryreferences/doc-standards.md — Formatting conventions, validationreferences/freshness-checklist.md — Audit targets and auto-fix rules
Reference Index
| Reference | When to Load |
|---|
references/doc-standards.md | When checking documentation standards |
references/freshness-checklist.md | When running freshness audits |
references/repo-architecture.md | When analyzing repo structure |
references/extended-workflows.md | Changelog generation, proofreading, freshness fix |
references/workload-documentation.md | Workload guide structure and lifecycle documentation |
