drafael/coding-harness / skills/explain-code
explain-code
UnverifiedExplain current code behavior, structure, runtime flow, data flow, and component ownership. Use for ordinary walkthroughs, line-by-line explanations, subsystem mental models, and questions about what code does or how it works. Use teach, when explicitly invoked and available, for progressive learning; technical-writing, when available, for substantial standalone documentation; clarify for expectation mismatches or historical intent; code-review for finding problems; refactor-code for structural changes; brainstorm for unresolved future design; and architect, when explicitly invoked and available, for implementation-ready structural design.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.5 KB |
| README.md | markdown | 2.6 KB |
| SKILL.md | skill md | 7.0 KB |
| references/explanation-patterns.md | markdown | 3.3 KB |
| references/exploration-playbook.md | markdown | 3.3 KB |
| references/language-notes.md | markdown | 2.4 KB |
references/explanation-patterns.md
View on GitHub# Explanation patterns
Choose the smallest pattern that fits the question. These are structures, not mandatory templates.
## Small function or snippet
Explain:
1. purpose in one sentence;
2. inputs and outputs;
3. execution order;
4. non-obvious expressions or branches;
5. side effects and errors;
6. relevant callers or context.
For line-by-line requests, group declarations and obvious forwarding code. Spend detail on state changes, branching, conversions, and language semantics.
## Algorithm
Start with the problem and invariant. Then explain initialization, each repeated step, termination, and result. Use a small concrete input when it clarifies the state transitions.
State time and space complexity only when derivable from the actual loops, recursion, operations, and data structures. Name assumptions, such as average constant-time hash lookup. Do not repeat a textbook complexity merely because the algorithm resembles a known one.
## Request or command flow
Trace:
- registration and entry point;
- parsed input;
- validation and authorization actually present;
- orchestration and domain calls;
- persistence or external calls;
- response or command result;
- error translation and cleanup.
Keep authentication, validation, and transport security separate. Do not infer one from another.
## Event-driven flow
Identify the producer, event shape, publication mechanism, consumer registration, handler behavior, state changes, acknowledgement semantics, and failure path. Explain ordering, duplication, and retry behavior only when established by code or configuration.
A sequence diagram is useful when several producers and consumers interact. A list is usually enough for one producer and one handler.
## Asynchronous or concurrent work
Explain who owns the task, when it starts, whether the caller waits, how results or failures propagate, what can run concurrently, and how cancellation and resources are handled.
Distinguish sequential syntax from actual scheduling behavior. Do not claim thread safety or race freedom without evidence.
## Database operation
Explain query construction, parameters, transaction boundary, execution, result mapping, and error handling. Mention pagination or locking when present.
Do not claim that indexes, pooling, prepared statements, isolation levels, or query optimization exist unless code, configuration, schema, or an execution plan establishes them.
## State machine or lifecycle
Name the states, transition triggers, guards, side effects, and terminal states. Note invalid transitions and recovery paths when implemented. A state diagram is helpful when prose would require repeatedly restating transitions.
## Component or subsystem
Use:
- overview;
- key concepts;
- trigger-to-result flow;
- component and ownership map;
- external boundaries;
- important files;
- gotchas and unresolved gaps.
Focus on the requested flow instead of inventorying every type.
## Diagrams
Use diagrams for relationships that are harder to hold in prose:
- sequence diagrams for interactions over time;
- flowcharts for decisions and transformations;
- state diagrams for lifecycle transitions;
- compact ASCII maps for simple containment or dependency relationships.
A diagram should add information or reduce cognitive load. Skip it when prose already makes the relationship clear. Reference real component and symbol names, and avoid decorative nodes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |