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.