docs-generator

Documentation Generator

Restructure project documentation for clarity and accessibility.

When to Use

Use this skill when the user requests a clearer README, organized project docs, API references, architecture diagrams, or contributor guidance. Select only the documentation files relevant to the detected project type.

Prerequisites

• Work in a git repository with a configured origin remote and a clean or safely stashed working tree.
• Identify the project's entry point, package manifest, test command, and existing documentation before drafting.
• Have write access to the target documentation paths; do not assume generated docs may replace source-authored content.

Repo Sync Before Edits (mandatory)

Before making any changes, sync with the remote to avoid conflicts:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty, stash first, sync, then pop. If origin is missing or conflicts occur, stop and ask the user before continuing.

Workflow

0. Create Feature Branch

Before making any changes:

1. Check the current branch - if already on a feature branch for this task, skip
2. Check the repo for branch naming conventions (e.g., feat/, feature/, etc.)
3. Create and switch to a new branch following the repo's convention, or fallback to: feat/docs-generator

1. Analyze Project

Scan the project to understand its shape.

Use sub-agents for parallel discovery. Launch multiple Agent tool calls concurrently to keep the main context clean:

• Agent 1 — Stack detection: Scan for package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, and identify the project type (library, API, web app, CLI, microservices), architecture (monorepo, multi-package, single module), and primary language(s). Return a structured summary.
• Agent 2 — Existing docs inventory: List all existing documentation files (README.md, docs/, CONTRIBUTING.md, CHANGELOG.md, etc.) and summarize their current state — present, missing, or outdated. Return a checklist.
• Agent 3 — User personas & project purpose: Read the main entry point, existing README, and any project description fields to determine the project's purpose, key features, and target user personas (end users, developers, operators). Return a short summary.