gpsaggese/helpers / .claude/skills/readme_file.write_architecture
readme_file.write_architecture
VerifiedWrite architecture documentation for a Python file
Goal
- Analyze the Python file
<FILE>passed by the user, and generate or update<FILE>.README.mdwith 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.mdexists, 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.mdfor markdown formatting.claude/skills/text.rules.mdfor text formatting
Update Document
- Write the results to
<FILE>.README.mdin 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:
Personfor external usersSystemfor external systemsContainerfor application containers/processesComponentfor internal componentsRelfor 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()callsvalidate_input()before computing results"
- E.g., "The function
- For assumptions:
- E.g., "This likely handles error cases based on the try-except blocks present"
- For facts (code-derived):
- 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.mdexists 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 466k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |