Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

python-api

Look up the public API of a Python package against the *installed version* and cache what's worth keeping. Four shapes by question type: (0) cache hit under `scratch/api/<lib>/<version>/`; (1) `inspect.signature` + `pydoc.render_doc` for a symbol; (2) `dir` / `pkgutil.iter_modules` for a module surface; (3) WebSearch + WebFetch of versioned docs for narrative ("how", "which", "what does X return when Y"). Never write a symbol from training-data memory — recognition is not a lookup. TRIGGER — any of: - About to name a symbol (function / class / method / arg) in code. - User asks "what's the signature of X?", "what's in module Y?", "how do I call X?", "which of A/B should I use?". - User asks "what does X return when <condition>?" (Shape 3 — see decision table). - Another workflow skill (`build-ml-pipeline`, `evaluate-ml-pipeline`, `iterate-from-skore`, `smoke-test-ml-pipeline`) says "consult the API skill". - About to reach for a library's "obvious" pattern from memory. SKIP when: the s

probabl-ai · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add probabl-ai/skills --skill python-api

About this skill


name: python-api description: > Look up the public API of a Python package against the installed version and cache what's worth keeping. Four shapes by question type: (0) cache hit under scratch/api/<lib>/<version>/; (1) inspect.signature + pydoc.render_doc for a symbol; (2) dir / pkgutil.iter_modules for a module surface; (3) WebSearch + WebFetch of versioned docs for narrative ("how", "which", "what does X return when Y"). Never write a symbol from training-data memory — recognition is not a lookup.

TRIGGER — any of:

  • About to name a symbol (function / class / method / arg) in code.
  • User asks "what's the signature of X?", "what's in module Y?", "how do I call X?", "which of A/B should I use?".
  • User asks "what does X return when ?" (Shape 3 — see decision table).
  • Another workflow skill (build-ml-pipeline, evaluate-ml-pipeline, iterate-from-skore, smoke-test-ml-pipeline) says "consult the API skill".
  • About to reach for a library's "obvious" pattern from memory.

SKIP when: the signature is obvious from a call site you just read in this turn; the work is filesystem / shell only (no Python symbols); a scratch/api/<lib>/<version>/<topic>.md cache file already answers the question (still a Shape 0 consultation — you just don't fetch).

HOW TO USE: resolve the package version first via a scratch file (scratch/<ts>_version_<pkg>.py with import <pkg>; print(<pkg>.__version__) — run with pixi run python scratch/<ts>_version_<pkg>.py). Then list scratch/api/<lib>/<version>/. Then pick the shape from the "What kind of question?" table. Narrative findings get cached back. All Python execution goes through scratch/<ts>_*.py files — inline python -c is forbidden regardless of length. Stack-specific orientation lives in references/stack_orientation.md — load on demand.

python-api

Discover the public API of any installed Python package, cache what matters, never trust training-data memory.

Three durable rules:

  1. Lookup against the installed version, never memory. Recognition is not a lookup. The version may have renamed / re-signatured / deprecated the symbol you remember.
  2. Cache to scratch/api/<lib>/<version>/<topic>.md so the next agent doesn't repeat the probe.
  3. Bundled references/ ≠ workspace cache. Bundled refs are durable workflow patterns; cache files are per-version extracts.

Next-step pointers

Came here for…After lookup, next is…
Symbol signature for code about to be written→ continue caller's flow (e.g. build-ml-pipeline § next step)
"Which library / which entry?"→ continue with the picked symbol; cache lands
Bootstrap turn (first workspace)→ required minimum cache lands; see references/bootstrap_cache.md
Failure debugging (KeyError / AttributeError)→ see Stop condition "Lookup failure ≠ artifact missing"

What kind of question? → Shape

Pick the shape by question type before picking a tool. Wrong shape produces a wrong-looking cache file and burns a turn.

The user's question is shaped like…Shape
"What's in scratch/api/<lib>/<version>/?" (always check first)0 cache hit
"Which entry point for <task>?"Stack orientation below, then Shape 1 / 1b to confirm
"What's the signature of X?" / "What args does X take?" / "What's the return type?"1b LSP hover (fast) → fall through to 1 if hover is sparse
"What does X do?" / "Full docstring of X?" (need Parameters / Examples / See Also)1 symbol card (pydoc)
"What's in module Y?" (open-ended discovery)2 module surface
"Search for symbols matching foo* across the env"2b LSP workspace symbol
"How does X work?" / "Which of A or B should I use?"3 narrative
"What does X return when <arg> is <value>?"3 narrative
"What's the recommended pattern for …?"3 narrative

Shape 3 is the right answer when the question depends on a condition over an argument. help() carries a Returns section but typically does not enumerate dispatch behaviour under each argument value — that lives in narrative docs.

Shape 1b vs Shape 1. Pyright hover gives the type signature (richer inferred return types than inspect.signature) + the first paragraph of the docstring — fast, no Python execution. Pydoc gives the full docstring with all sections — slower but authoritative. Default escalation: 1b first for "what's the signature"; fall through to 1 if hover is empty / one-liner.

Prerequisites for Shape 1b / 2b (LSP shapes). Pyright available via opencode LSP AND pyrightconfig.json pointing at the lsp env. If either is missing, LSP shapes are unavailable — use Shape 1 / 2 directly. The agent feature: installed row in JOURNAL.md Status Workspace decisions is the precondition; see python-env-manager § Agent feature.

Stop conditions — read before any lookup

  • No symbols from memory. Every function / class / method / arg must come from a lookup this turn — inspect.signature, a scratch/api/<lib>/<version>/ file, or a fresh WebFetch. Recognition does not count. Sticky named cases — full list in references/named_traps.md:
    • skrub: tabular_learner → tabular_pipeline in 0.7+.
    • skrub: mark_as_y(target_column) → signature dropped the positional arg in 0.9+; use .skb.select("...") before mark.
    • skore: Project.get(...) is by id, not user-facing key; enumerate via project.summarize() first.
  • Never fabricate a probe result. If the probe hasn't executed, the Signature / help() sections must remain blank or marked <pending probe execution>. Same rule for Shape 3: do not paraphrase docs from memory; cache file holds verbatim extracts.
  • Version-correct first. Resolve <pkg>.__version__ before any lookup. The version subf
Read the complete source ↗