repo-documenter

timbuchinger's avatarfrom timbuchinger

Provide repository-wide documentation guidelines under `docs/`. Use tool-based inspection first, and keep `README.md` and `docs/` in sync with the current state of the app.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025
[Technical Writing]

When & Why to Use This Skill

The Repository Documenter skill automates the generation and maintenance of high-quality, repository-wide documentation. By utilizing tool-based inspection and predefined templates, it ensures that README files, architecture diagrams, and system overviews remain perfectly synchronized with the actual state of the codebase, significantly reducing documentation rot and improving project maintainability.

Use Cases

  • Automated Documentation Sync: Keeping the README.md and docs/ directory updated automatically as the application code and infrastructure evolve.
  • Architecture Visualization: Generating and maintaining Mermaid diagrams to provide clear, visual representations of system components and data flows directly within the documentation.
  • Standardized Project Onboarding: Creating a consistent documentation structure (system-overview, usage guides, and architecture index) for new repositories to help new developers get up to speed quickly.
  • Technical Documentation Auditing: Using tool-based introspection to identify and fill gaps in existing technical docs, ensuring they reflect the 'current reality' of the software rather than outdated assumptions.
namerepo-documenter
description"Provide repository-wide documentation guidelines under `docs/`. Use tool-based inspection first, and keep `README.md` and `docs/` in sync with the current state of the app."

Repository Documenter Skill

General Guidance

This skill defines and maintains documentation guidelines for the repository. Primary documentation lives under:

docs/

Always use tool-based inspection first (MCP tools if configured). Only fall back to CLI when necessary.

Documentation must always reflect current reality, not assumptions.

When asked to update documentation:

  1. Inspect existing docs (if any).
  2. Inspect code/configs/infrastructure via tools.
  3. Determine which documentation files make sense for this project.
  4. Create/update only relevant files.
  5. Never guess — ask for confirmation if unclear.
  6. Use Mermaid diagrams where they add clarity.

Documentation Structure

Index File (MANDATORY)

Always create docs/architecture/index.md as the main architecture entry point when architecture documentation is needed. For repository-level docs, ensure docs/ contains an appropriate index.md or similar entry point for the reader.

This file should:

  • Provide a brief overview of the system
  • Link to other documentation pages (if any exist)
  • Explain the system or repository structure in a way that's readable on its own
  • Include a high-level diagram of key components where helpful

Optional Supporting Documentation Files

Only create additional files if the repository complexity warrants them. Use these templates when relevant (templates live in the skill directory):

  • system-overview.md
  • cloud-architecture.md
  • service-architecture.md
  • cicd-architecture.md

You can also create custom documents based on the project's specific needs (for example data-architecture.md, security-architecture.md, api-architecture.md, or usage.md).

Templates

Template files are provided in this skill directory and may be adapted to fit the project. Remove sections that don't apply, add sections that are needed.

  • index.md - Entry point template
  • system-overview.md - Optional system-level template
  • cloud-architecture.md - Optional cloud infrastructure template
  • service-architecture.md - Optional service/API template
  • cicd-architecture.md - Optional CI/CD pipeline template

Behavioral Rules

  • MANDATORY: Ensure architecture entry points exist under docs/architecture/ when architecture content is required.
  • Use tool-based introspection before CLI.
  • Ask for files or context when uncertain.
  • Only create additional documents if the repository complexity warrants them.
  • Update diagrams to match reality.
  • Keep diagrams readable and scoped.
  • Maintain consistency across documents.
  • Filenames: All filenames MUST be lowercase and use dashes (-) as word separators. Do not use spaces or underscores.
  • README maintenance: Keep the repository README.md up to date with the current state of the application. Prefer an overview-only README that links to the relevant docs/ pages for detailed information.
  • Suggested (non-mandatory): Add docs/usage.md to provide detailed usage guidelines and examples for users.
  • If a suggested template doesn't fit, adapt or skip it.
  • When in doubt about which files to create, ask the user.

Notes

  • When adding docs/usage.md, include a Recommended section near the top with the preferred, simple way to run the app and an optional minimal example config if the app requires configuration.