gpsaggese/helpers / .claude/skills/readme_file.write_architecture
readme_file.write_architecture
VerifiedWrite architecture documentation for a Python file
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
SKILL.md
View on GitHub---
description: Write architecture documentation for a Python file
model: sonnet
---
# 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.,
```text
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:
```markdown
- 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`
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: 472k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |