docs-writer

name	docs-writer
description	Maintains repository documentation accuracy and freshness; use for doc updates, agent or skill changes, staleness checks, changelog entries, and repo explanation requests.
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:

• 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

Step-by-Step Workflows

Workflow 1: Update Existing Documentation

1. Identify target files: Determine which files in site/src/content/docs/ need updates.
2. Read latest version: Always read the current file before editing.
3. Load standards: Read references/doc-standards.md for conventions.
4. Apply changes: Follow the doc-standards conventions strictly:
   • 120-char line limit (CI enforced)
   • Single H1 rule (title only)
   • File header: # {Title} + > Version {X.Y.Z} | {description}
   • Version number from VERSION.md (single source of truth)
5. Verify links: Check all relative links resolve to existing files.
6. Run validation: Offer to run npm run lint:md and npm run lint:links.

Workflow 2: Add Documentation for New Entity

When a new agent or skill is added to the repo:

1. Read architecture: Load references/repo-architecture.md for current entity inventory and naming conventions.
2. Identify all files needing updates:
   • New agent → update README.md (root) agent references
   • New skill → update README.md (root) skill references
3. Match existing patterns: Study adjacent entries in each table to match column format, emoji conventions, and description style.
4. Update references: Use descriptive language per the no-hardcoded-counts instruction — never hard-code entity totals.
5. Cross-reference check: Search for other files referencing the entity and add it to the appropriate tables.

Workflow 3: Freshness Audit (Staleness Check)

1. Load checklist: Read references/freshness-checklist.md.
2. Scan each audit target:
   • Version numbers match VERSION.md
   • Agent/skill counts match filesystem
   • Tables list all entities present in filesystem
   • No references to removed/renamed agents
3. Check project health files:
   • Read QUALITY_SCORE.md — verify grades still reflect reality
   • Read tools/tests/exec-plans/tech-debt-tracker.md — verify items still relevant
4. Report findings: Present a table of issues found with:
   • File path, line number, issue description, suggested fix
5. Auto-fix: For each issue, propose the exact edit and apply it after user confirmation (or immediately if user said "fix all").
6. Update health metrics: If fixes change quality grades, update QUALITY_SCORE.md.

Workflow 4: Explain the Repo Architecture

1. Load architecture: Read references/repo-architecture.md.
2. Answer questions: Use the reference to explain how components connect — agents, skills, instructions, templates, artifacts, and the multi-step workflow.
3. Cite sources: Point to specific files when answering.
4. Stay current: If the reference seems outdated vs. filesystem, note the discrepancy and offer to update the reference.

Workflow 5: Generate Changelog Entry

Classify commits by conventional commit type, format as Keep a Changelog entry, determine version bump. See references/extended-workflows.md for full steps.

Workflow 6: Proofread Documentation

Three-layer review: language quality (Vale + manual), tone/terminology (glossary), technical accuracy (filesystem ground truth). See references/extended-workflows.md for full steps.

Workflow 7: Process Freshness Issues

Trigger: "Fix the docs freshness issue" or docs-freshness label. Read issue body → apply fixes → run npm run lint:docs-freshness → summarize.

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
Version mismatch	Read VERSION.md and propagate to all docs
Count mismatch	List .github/agents/ and .github/skills/ directories

References

• references/repo-architecture.md — Repo structure, entity inventory
• references/doc-standards.md — Formatting conventions, validation
• references/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