gpsaggese/helpers / .claude/skills/readme_file.explain_code
readme_file.explain_code
VerifiedDocument a Python file's classes, functions, and relationships in markdown
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.4 KB |
SKILL.md
View on GitHub---
description: Document a Python file's classes, functions, and relationships in markdown
model: sonnet
---
# 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_auction` for `batch_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:
```markdown
- 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 `# Verification` checklist 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.,
```markdown
- `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.,
```markdown
# 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.,
```markdown
# 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.,
```markdown
# 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.,
```markdown
# 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.,
```markdown
# 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.md` and `.claude/skills/text.rules.md`
for 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |