Skip to content

gpsaggese/helpers / .claude/skills/readme_file.write_architecture

readme_file.write_architecture

Verified

Write architecture documentation for a Python file

Goal

  • Analyze the Python file <FILE> passed by the user, and generate or update <FILE>.README.md with bullet-point documentation of its architecture, code organization, idioms, and so on

Workflow

Read File

  • Read <FILE> to understand its structure:
    • Parse all function and class definitions
    • Identify the public API (exported functions, classes, constants)
    • Trace which functions call which
    • Identify external dependencies (imports from other modules, libraries)
    • Note the module's purpose and role in the broader system

Check the Existing Readme

  • If <FILE>.README.md exists, read it and plan what to update. Otherwise, plan the content from scratch
  • Make sure the docstring of the corresponding file points to <FILE>.README.md, e.g.,
    For a description of the architecture of this file, see the file
    <FILE>.README.md
    

Generate Document

  • Follow the template .claude/templates/architecture_doc.template.md
  • Generate the sections in markdown with bullet points, following:
    • .claude/skills/markdown.rules.md for markdown formatting
    • .claude/skills/text.rules.md for text formatting

Update Document

  • Write the results to <FILE>.README.md in the same dir as <FILE>
  • Wrap the text at 85 columns

Conventions

  • Use conventions summarized in docs/documentation_meta/all.architecture_diagrams.explanation.md
  • Use PlantUML diagrams (```plantuml) for all architecture diagrams, never Mermaid, following .claude/skills/C4.rules.md
  • Use the standard C4 layout in PlantUML:
    • Person for external users
    • System for external systems
    • Container for application containers/processes
    • Component for internal components
    • Rel for relationships between elements
  • Label diagrams with what they show
  • Reference real code artifacts (function names, class names, file paths) when available
  • Distinguish facts from assumptions:
    • For facts (code-derived):
      • E.g., "The function process_data() calls validate_input() before computing results"
    • For assumptions:
      • E.g., "This likely handles error cases based on the try-except blocks present"
  • Focus on:
    • Maintainability: How easy is it to modify and extend this code?
    • Extensibility: How well does the design accommodate new features?
    • Operational understanding: What must someone know to work with this code?
  • Say how the doc was generated, with this line right after the title:
    - Generated by `.claude/skills/readme_file.write_architecture/SKILL.md`
    

Constraints

  • Do not modify <FILE>. Only create or update <FILE>.README.md
  • Do not over-document: skip what the code makes obvious
  • Keep diagrams focused: one clear diagram beats three cluttered ones
  • Do not invent architecture that is not in the code
  • When unsure of the intent, mark the observation as an assumption
  • Do not use emojis or decorative formatting

Verification

  • <FILE>.README.md exists and documents the architecture of <FILE>
  • The docstring in <FILE> references <FILE>.README.md
  • Diagrams use PlantUML syntax with the C4 element types
  • No architecture is invented that is not in the code
  • The architecture doc says it was generated by .claude/skills/readme_file.write_architecture/SKILL.md
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: 466kUpdated 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: 196kUpdated 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: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall