gpsaggese/helpers / .claude/skills/notebook.create_api_intro
notebook.create_api_intro
VerifiedCreate a notebook to present the API of a package
Goal
- Create a self-contained Jupyter notebook that teaches the Python package
<PACKAGE_NAME>: its core primitives, mental model, and API surface - Optimize the notebook for learning the library, not for a large real-world problem
Teaching Philosophy
-
Follow this teaching philosophy:
- Start from the smallest possible working example
- Introduce one new concept at a time
- Use the minimum code needed to demonstrate each concept
- Prefer toy examples with 2-5 objects over realistic datasets
- Every code cell should answer exactly one question
- Avoid helper functions, abstractions, and boilerplate unless they are part of the library's API
- Focus on understanding:
- What are the primitive objects?
- How are they created?
- How do they interact?
- What methods are available?
- What state do they hold?
- How do they compose into larger structures?
Notebook Structure
Name of the Notebook
- The notebook name
<FILE>is given by the user or generated as:tutorials/<PACKAGE_NAME>/<PACKAGE_NAME>.<ID>.API.<DESCRIPTION>.ipynb - E.g., for
pgmpyand probabilistic inference:tutorials/pgmpy/pgmpy.01.API.probabilistic_inference.ipynb
Use Standard Template Structure
- Use
.claude/templates/notebook.template.pyfor notebook initialization- Follow the cell layout in
.claude/skills/notebook.rules.mdunder## Use Standard Template Structure: title cell with scope and pedagogical arc, optional pip cell, autoreload and third-party imports cell, and a last setup cell that callsutils.init_loggers(_LOG) - Do not add an
## Importsheader
- Follow the cell layout in
Follow General Notebook Conventions
- Follow the conventions in
.claude/skills/notebook.rules.md:# Design Principles and Setup: Template structure and Python code rules# Cell Design and Content: Python style, showing results, and pandas tables# Text and Markdown Formatting: Bullet points, em dash replacement, and LaTeX# Visualization and Interactivity: Data manipulation and plotting## Visualization Cell Triplet Details: Cells with visualizations or widgets
Follow the Template
- The template is
.claude/templates/API_notebook.template.ipynb - In the title cell, right after the title, add:
- Generated by `.claude/skills/notebook.create_api_intro/SKILL.md`
Library Overview
- Briefly explain the problem the library solves, its key abstractions, its most important classes, and a conceptual diagram of how the pieces fit together
Primitive-by-Primitive Exploration
-
For each important primitive:
-
Mental Model
- Explain what the object "means"
- Present as a markdown table (see "Mental Model as Markdown Table" below)
-
Smallest Construction
# Minimal example in Python -
Explain the important Methods
-
Inspect the Object using
type,dir, andhintros.get_public_methods_as_str(obj)fromhelpers/hintrospection.py
-
-
Synthesize the core mental model
- What are the fundamental abstractions?
- How do they fit together?
-
Write 2-4 sentences that capture the essence of the library's design
Mental Model as Markdown Table
- Present the mental model as a markdown table, not bullet points:
- Why: Tables are scannable and show complex API relationships clearly
- Columns: Object | Description | Comments/Type
- Examples:
- LIME:
LimeTabularExplainer | Configured explainer | Wraps model + training data - SHAP:
Explanation.values | SHAP contributions | (n_samples, n_features) array
- LIME:
- Placement: In a markdown cell early in "Primitive 1", after the
bullet-point overview
| Object | Description | Additional Info | |--------|-------------|-----------------| | `Explainer(...)` | Main class | Wraps data/model | | `explainer.method(x)` | Instance method | Returns result object | | `Result.values` | Data array | shape (n, m) |
Composition Examples
-
Build progressively:
- Example 1:
- Smallest meaningful object
- Example 2:
- Add one new concept
- Example 3:
- Combine two primitives
- Example 4:
- Minimal end-to-end workflow
- Example 1:
-
Each example should fit within roughly 10-20 lines
API Patterns
-
Identify recurring patterns:
- Builder patterns
- Fit/predict patterns
- Graph construction patterns
- Context managers
- Iterators
- Serialization
- Configuration
-
Show the smallest example of each pattern
Interactive Exploration
- Provide cells that encourage experimentation
- Add questions such as:
- What happens if you remove this argument?
- What is the default value?
- What type is returned?
Link to Source Code
- Use
hintros.print_obj_info(obj)fromhelpers/hintrospection.pywhenever a class, function, or method is introducedobjis the Python object itself (class, function, method, or module), not a string- It prints the public interface as markdown, then a GitHub link to the exact
file and line, e.g.,
https://github.com/<ORG>/<REPO>/blob/<BRANCH>/<PATH>#L<LINE>
- Call it right after "Smallest Construction" or "Inspect the Object", so readers
can jump to the implementation, e.g.,
import helpers.hintrospection as hintros # Link to the class definition on GitHub, and list its public surface. hintros.print_obj_info(sim.MultiArmedBandit)
Comment Each Function
- For each function call, explain what it does, then comment on its outcome
- E.g.,
# Call `GET /openapi.json` to fetch the schema `FastAPI` generated automatically. response = demo_client.get("/openapi.json") schema = response.json() _LOG.info("OpenAPI title: %s", schema["info"]["title"]) _LOG.info("Registered paths: %s", sorted(schema["paths"].keys())) # Outcome: 200 OK; the schema lists every route registered on `demo_app` above.
Special Instructions
- Use executable Python code throughout
- Minimize imports
- Keep examples independent whenever possible
- Do not skip intermediate steps
- Avoid advanced topics until all primitives are covered
- Prefer many tiny examples over a few large examples
- If the library has hidden state or non-obvious behavior, explicitly inspect it
- Whenever a class is introduced, show:
- Construction
- Inspection
- Mutation
- Interaction with another object
- The notebook should feel like a guided reverse-engineering of the library's design
Verification
- Create paired Python
> jupytext.py --action pair --files <FILE>.ipynb - Make sure that the notebook runs end-to-end
> cd tutorial/<PACKAGE_NAME> > docker_cmd.sh "python /git_root/tutorials/<PACKAGE_NAME>/<FILE>.py" - The title cell of the notebook says that it was generated by
.claude/skills/notebook.create_api_intro/SKILL.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |