maintain-docs

Update OVERVIEW.md and AGENTS.md breadcrumbs via a doc-only gated PR.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/bketelsen/ytsejam --skill maintain-docs-bketelsen
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: maintain-docs
Source: https://github.com/bketelsen/ytsejam/tree/main/contrib/skills/maintain-docs
Command: npx skills add https://github.com/bketelsen/ytsejam --skill maintain-docs-bketelsen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Keep AI-facing repository documentation current and aligned with the codebase, ensuring the overview and subsystem docs reflect changes and that AGENTS.md breadcrumbs point to the docs path. It enables doc-only maintenance with a gated PR to keep docs synchronized with evolving code.

Core Features & Use Cases

  • Update docs/agents/OVERVIEW.md to reflect code structure, architecture, key patterns, and configuration.
  • Create or refresh subsystem docs and ensure AGENTS.md breadcrumb links to the documentation suite.
  • Publish updates as a single gated PR without touching code, enabling safe, auditable documentation maintenance.

Quick Start

Run the maintain-docs workflow to refresh docs/agents/OVERVIEW.md and ensure AGENTS.md breadcrumb, by submitting a single, doc-only PR.

Frequently Asked Questions about maintain-docs

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

FAQPage Schema
How do I keep AI-facing repository documentation in sync with code changes?

AI-facing repository documentation is kept in sync by identifying code changes and updating OVERVIEW.md and subsystem docs, then submitting the updates as a single gated PR to ensure docs reflect the current codebase.

What is the best way to update OVERVIEW.md and AGENTS.md breadcrumbs without touching code?

Updating OVERVIEW.md and AGENTS.md breadcrumbs without touching code uses a doc-only workflow that consolidates documentation changes into a single gated PR, ensuring safe, auditable documentation maintenance while leaving the codebase untouched.

Does this documentation maintenance workflow require existing subsystem docs to run?

Yes, this documentation maintenance workflow requires a repository with an existing overview and subsystem docs to function, ensuring the OVERVIEW.md and AGENTS.md breadcrumb can be properly validated and refreshed.

How do I validate AGENTS.md breadcrumb integrity after updating repository docs?

Validating AGENTS.md breadcrumb integrity happens automatically during the doc-only workflow, checking that breadcrumb links correctly point to the updated documentation suite path before consolidating changes into a single gated PR.

Can I refresh multiple subsystem docs in a single pull request?

Refreshing multiple subsystem docs in a single pull request is supported by consolidating all documentation updates, including OVERVIEW.md and AGENTS.md changes, into one gated PR for safe and auditable maintenance.

When should I not use a doc-only PR workflow for repository documentation?

A doc-only PR workflow for repository documentation should not be used when the repository lacks an existing overview or subsystem docs, as the workflow depends on these structures to validate and update the documentation suite.