skills.rest
macalbert
macalbertCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

doc-maintenance

Updates changelogs, READMEs, and documentation files following defined categories and validation workflows.

138|5|Updated Sep 19, 2024
Search Tags:#changelog#documentation#markdown#readme#release notes#lint#doc maintenance
One-click install
npx skills add https://github.com/macalbert/envilder --skill doc-maintenance-macalbert
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: doc-maintenance
Source: https://github.com/macalbert/envilder/tree/main/.github/skills/doc-maintenance
Command: npx skills add https://github.com/macalbert/envilder --skill doc-maintenance-macalbert

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping changelogs, READMEs, and docs synchronized with code changes is tedious and error-prone, leading to stale documentation and inconsistent changelog entries across components. ## Core Features & Use Cases - Changelog Entry Authoring: Write entries using standardized categories (Added, Changed, Fixed, Documentation, Dependencies, Security) with user-impact-oriented bullets and issue/PR references. - Scoped Documentation Updates: Locate and update the smallest set of affected files across per-component changelogs, CLI docs, GitHub Action docs, SDK READMEs, and architecture docs. - Validation Workflow: Verify edits with pnpm lint and website builds, and delegate cross-surface drift detection to the doc-sync skill. - Use Case: After merging a bug fix for Azure Key Vault timeouts, add a Fixed entry to the CLI changelog, update the affected docs, and run lint to confirm formatting consistency. ## Quick Start Add a changelog entry for the latest bug fix and update any README sections affected by the change.

Frequently Asked Questions about doc-maintenance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a changelog entry for a new feature?▼

Add a bullet under the `Added` category in the current release section of the component's changelog. Start with an action verb, keep it user-impact oriented, and reference the issue or PR number when available.

What changelog categories should I use for dependency updates?▼

Use the `Dependencies` category for dependency updates. Other categories include `Added` for new features, `Changed` for behavior changes, `Fixed` for bug fixes, `Documentation` for docs-only changes, and `Security` for security-related changes.

How do I validate documentation changes after editing?▼

Run `pnpm lint` to check formatting and consistency after documentation edits. For website-related docs, also run `pnpm build` inside the `src/website` directory to verify the build succeeds.

What is the difference between doc-maintenance and doc-sync?▼

doc-maintenance covers how to write and update documentation, including changelog format and editing workflow. doc-sync covers how to detect drift across documentation surfaces, and is used for comprehensive cross-surface audits.

When should documentation edits be avoided?▼

Avoid documenting features that do not exist in code, and never modify ROADMAP.md without an explicit request since it is strategic. Always verify claims against current source files before writing.

Related Skills

Explore More Software Engineering Skills→
chris-prenerchris-prener

readme

Audits and updates README.md to match the current codebase state.

Community
Advanced
seanwachsseanwachs

update-release-notes

Draft and publish categorized release notes to Confluence after PR approval.

Community
Advanced
rnwolfernwolfe

docs-audit

Audit README.md and STATUS.md against shipped code for documentation drift.

Community
Intermediate
psengerpsenger
9

git-commit-pr-message

Generate conventional git commit messages, PR titles, and changelog entries from staged changes.

Community
Advanced