Project Documentation

Project Documentation Companion

This skill complements the upstream documentation-writer skill. Use it to add project-aware documentation judgement on top of Diátaxis guidance.

When to use this skill

Use this skill when you need to:

• Write or update project documentation that should reflect the repository's goals, scope, and conventions.
• Decide whether content belongs in README.md, docs/, or another project-owned Markdown file.
• Keep documentation concise, grounded in the codebase, and consistent with local terminology.

Layering

Treat the writing stack as three layers:

1. documentation-writer - Diátaxis framework, audience clarification, and document structure.
2. This skill - project-aware placement, terminology, and review rules.
3. The active repository context files - the source of truth for goals, scope, conventions, and local standards.

Workflow

1. Start by applying the documentation-writer skill for document type, audience, goal, and scope.
2. Read any available context files before drafting:
   • GOALS.md
   • SCOPE.md
   • CONVENTIONS.md
   • AGENTS.md
3. Ground all terminology and recommendations in those files. Do not invent missing context.
4. Choose the document location using references/document-placement.md.
5. If a template or starter structure would help, use the relevant file in assets/.
6. Before finishing, run through references/review-checklist.md.

Scope boundaries

• This skill is for project documentation, not ADR authoring.
• If the user wants to create or update an ADR, use the dedicated create-architectural-decision-record skill instead.
• Do not duplicate ADR templates or ADR process rules here.

Writing rules

• Keep prose concise and specific.
• Prefer task-oriented guidance over feature tours.
• Reflect the repository's actual structure and workflows rather than generic boilerplate.
• When context files and existing docs disagree, flag the mismatch rather than silently picking one.

References

• references/document-placement.md - decide where content should live.
• references/review-checklist.md - final review checks.
• assets/readme-section-template.md - starter for short README sections.
• assets/how-to-template.md - starter for task-focused how-to guides.
• assets/tutorial-template.md - starter for learning-oriented tutorials.
• assets/technical-blog-template.md - starter for technical blog posts.