Skip to content

gpsaggese/helpers / .claude/skills/notebook.create_api_intro

notebook.create_api_intro

Verified

Create 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:

    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:
    - 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
      | 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.,
    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
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 117kUpdated Claude CodeCodexVerifiedInstall
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: 117kUpdated Claude CodeCodexVerifiedInstall