Skip to content

divar-ir/ai-doc-gen / skills/generate-readme

generate-readme

Verified

Generate or refresh a comprehensive, professional README.md for a repository, with architecture overview, mermaid and optional C4 diagrams, repository structure, dependencies, and API documentation. Use whenever the user asks to create, write, update, improve, or regenerate a README, project documentation, or a project overview page — even if they just say "document this project" or "this repo needs docs".

Generate README

Transform codebase analysis into a clear, welcoming README.md that helps engineers quickly understand the project.

Workflow

1. Gather analysis data

Check for existing analysis documents in <repo>/.ai/docs/ (structure, dependency, data-flow, request-flow, API analyses). They may have been produced by the analyze-codebase skill.

  • If they exist: use them as your primary source, but spot-check key claims against the code — they may be stale.
  • If they don't exist: offer to run the analyze-codebase skill first (better results, reusable artifacts). If the user declines or wants it quick, explore the codebase directly yourself before writing.

2. Handle the existing README

Ask the user (or infer from their request) whether to incorporate the existing README:

  • Incorporate (default when a README exists): read it first; keep useful, still-accurate information — especially manually written content like setup quirks, badges, links, and licensing. Verify claims against the code; the old README may be outdated.
  • From scratch: ignore the existing file entirely.

3. Write the README

Include the following sections, in this order, unless the user excludes some. Only use these headlines plus any carried over from the existing README — don't invent extra sections.

  • Project Overview — title, concise description, purpose, key features, likely use cases.
  • Table of Contents — for READMEs long enough to need one.
  • Architecture — high-level overview, technology stack, component relationships with a mermaid diagram, key design patterns.
  • C4 Model Architecture (optional, skip unless the project's complexity warrants it or the user asks) — context and container diagrams as mermaid, wrapped in <details>/<summary> tags. Only include levels that can be reasonably deduced from the codebase.
  • Repository Structure — important directories and key files with their roles. Keep minimal and concise.
  • Dependencies and Integration — internal/external service dependencies, message queues, event streams. Do not list ordinary libraries here.
  • API Documentation — endpoints and request/response formats in an easy-to-read form (tables work well). No raw proto/schema dumps.
  • Development Notes — project-specific conventions, how to run/test, performance considerations.
  • Known Issues and Limitations — TODOs/FIXMEs found in code, incomplete features, technical debt.
  • Additional Documentation — markdown links to other docs in the repository.

Writing guidelines

  1. Use only information that can be reasonably inferred from the code and repository structure — never invent capabilities, and describe existing code, not hypothetical code.
  2. Do not include or reference any file from the .ai/docs/ directory — those are internal AI artifacts.
  3. Format with proper Markdown: headings, syntax-highlighted code blocks, lists, and tables.
  4. Make the README welcoming and clear for developers new to the project.
  5. For mermaid diagrams: group by logical boundaries, use meaningful relationship labels with descriptive verbs, keep visual hierarchy clean, and prefer several small focused diagrams over one giant one.
  6. Note (in your report to the user, not the README) any areas where additional documentation would help.

4. Report

Write the file to <repo>/README.md, then summarize for the user what changed versus the previous README (if any) and flag anything you couldn't verify from the code.

rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall