gpsaggese/helpers / .claude/skills/readme_file.explain_code
readme_file.explain_code
VerifiedDocument a Python file's classes, functions, and relationships in markdown
Goal
- Read the Python files passed by the user and write
explain_code.<descr>.md, documenting their classes, functions, interfaces, and relationships
Workflow
Read the Files
- Read every Python file
<FILE>passed by the user or referenced in the request
Generate the Document
- Write the file in the current directory as
explain_code.<descr>.md<descr>is a short slug, typically the source file's basename without extension (e.g.,batch_call_auctionforbatch_call_auction.py); use a combined slug for several files
- Say in the output file how it was generated, with this line right after the title:
- Generated by `.claude/skills/readme_file.explain_code/SKILL.md` - Include the five sections below, in this exact order
- Under each section, print one level-2 header (
##) per file read, using the same path used to read it (this disambiguates files with the same basename) - Omit a section, or a file's subsection within it, entirely if there is nothing
to report; never print an empty header or a placeholder bullet like
- - Print the result only to the file, not to the screen
Verify
- Follow the
# Verificationchecklist below before returning the result
File Description
-
Print a nested bullet list per file: its abstractions and functionalities
-
Order files by use relationship
- E.g., if file X is imported by Y, then X comes before Y in the list
-
E.g.,
- `batch_call_auction.py` - In-memory order book for a batch call auction - Queues buy/sell orders, buckets by capability tier - Clears each tier at a uniform price once per round - `passthrough_proxy.py` - LLM provider gateway - Routes a prompt to a registered provider - Times the call, estimates cost, and logs every request/response pair for later query
Class Description
-
For each file, print one bullet per class, with a description under 20 words
-
E.g.,
# Class Description ## `research/Noesis/batch_call_auction.py` - `Bid` - Buyer order: (tasks, min tier, max latency, min reliability, max price) - `Ask` - Seller order: (tasks, tier, typical latency/reliability, min price) - `Fill` - One matched buyer/seller trade at a tier's uniform clearing price - `TierClearResult` - Outcome of clearing one tier (price, fills, unfilled quantities) - `OrderBookStore` - Abstract pluggable storage backend for pending bids/asks ## <file.py> ...
Class Interface
-
For each file, print every class with the class it descends from (or
(dataclass)if it has no explicit base) and a nested bullet per method with its full signature and a description under 20 words -
If a class defines no custom methods (e.g., a plain dataclass with only an auto-generated constructor), say so instead of listing a signature
-
E.g.,
# Class Interface ## `research/Noesis/batch_call_auction.py` - `Bid(dataclass)` - `__init__(self, buyer_id: str, n_tasks: int, c_level_min: str, l_max: float, r_min: float, p_max: float) -> None` - Validates and stores one buy order - `Fill(dataclass)` - Plain data holder, no custom methods - `OrderBookStore(abc.ABC)` - `add_bid(self, bid: Bid) -> None` - Queue a bid - `clear(self) -> None` - Abstract, drop every stored bid/ask ## <file.py> ...
Function Interface
-
For each file, list module-level functions only, i.e., those defined outside any class (methods are covered under Class Interface)
-
Include underscore-prefixed functions when they hold core logic; skip trivial one-line helpers
-
One line per function: full signature and a description under 20 words
-
E.g.,
# Function Interface ## `research/Noesis/batch_call_auction.py` - `_match_orders_in_tier(c_level: str, bids: List[Bid], asks: List[Ask]) -> TierClearResult` - Matches one tier's bids/asks and computes uniform clearing price ## <file.py> ...
Function Relationship
-
For each function in
# Function Interface, list its callers and callees, scoped to the files read -
Skip trivial delegations already implied by
# Class Relationships(e.g., a method that only forwards to a stored collaborator) -
E.g.,
# Function Relationship ## `research/Noesis/batch_call_auction.py` - `_match_orders_in_tier()` - **Called by**: `OrderBook.clear_round()`, once per capability tier - **Calls**: no other functions in this file ## <file.py> ...
Class Relationships
-
Print relationships among all classes read, grouped under level-2 headers
-
Typical groups:
## Inheritance,## Composition,## Uses, and## Mirrors(schema correspondence with no code dependency). Include a group only if it applies, and list only classes where the relationship holds -
E.g.,
# Class Relationships ## Inheritance - `OrderBookStore` - `_InMemoryOrderBookStore` from `batch_call_auction.py` - `PostgresOrderBookStore` from `postgres_store.py` ## Composition - `OrderBook` - Holds one `OrderBookStore` ## Uses - `OrderBook.clear_round()` calls `_match_orders_in_tier()` per capability tier and returns `Dict[str, TierClearResult]` - `TierClearResult` aggregates `List[Fill]` ## Mirrors - `BidRequest` (API layer) <-> `Bid` (matching engine): same fields, no shared code
Conventions
- Follow
.claude/skills/markdown.rules.mdand.claude/skills/text.rules.mdfor markdown and text formatting - Keep every bullet description under 20 words
- Enclose class names, function names, and file paths in backticks
Constraints
- Do not modify the Python files being read
- Base every bullet strictly on what the code shows; do not invent classes, functions, or relationships that are not present
- Never print an empty section header or a placeholder bullet (
-with no text)
Verification
- Every class and function name mentioned exists in a file that was read
- Every file that was read appears as a level-2 header in each section where it has content, using the same path used to read it
- No section or subsection is present with zero bullets under it
- Every description is under 20 words
- The output file says that it was generated by
.claude/skills/readme_file.explain_code/SKILL.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |