gpsaggese/helpers / .claude/skills/notebook.create_api_intro
notebook.create_api_intro
VerifiedCreate a notebook to present the API of a package
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
SKILL.md
View on GitHub---
description: Create a notebook to present the API of a package
model: sonnet
---
# 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:
1. Start from the smallest possible working example
2. Introduce one new concept at a time
3. Use the minimum code needed to demonstrate each concept
4. Prefer toy examples with 2-5 objects over realistic datasets
5. Every code cell should answer exactly one question
6. Avoid helper functions, abstractions, and boilerplate unless they are
part of the library's API
7. 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 `pgmpy` and probabilistic inference:
`tutorials/pgmpy/pgmpy.01.API.probabilistic_inference.ipynb`
## Use Standard Template Structure
- Use `.claude/templates/notebook.template.py` for notebook initialization
- Follow the cell layout in `.claude/skills/notebook.rules.md` under
`## 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 calls `utils.init_loggers(_LOG)`
- Do not add an `## Imports` header
## 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:
```markdown
- 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`, and
`hintros.get_public_methods_as_str(obj)` from `helpers/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`
- **Placement**: In a markdown cell early in "Primitive 1", after the
bullet-point overview
```markdown
| 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
- 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)` from `helpers/hintrospection.py` whenever a
class, function, or method is introduced
- `obj` is 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.,
```python
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.,
```python
# 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: 119k | 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: 119k | 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: 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: 118k | Updated | Claude CodeCodex | Verified | Install |