AgentSkillsCN

make-program-tutorial

当用户希望使用Pixi创建一个自托管、可离线安装的Conda通道（镜像），并包含特定的软件包子集时，可使用此技能。

SKILL.md
--- frontmatter
name: make-program-tutorial
description: Manual invocation only; use only when the user explicitly requests `make-program-tutorial` by exact name, OR when the user asks to use a skill to create an SDK/API/library tutorial. Create a clear, reproducible, step-by-step tutorial for a specific API/SDK/library (or a set of functions/classes), with runnable examples, expected outputs, and basic troubleshooting.

Make Program Tutorial

Inputs to Collect (ask if missing)

  • •Target topic:
    • •Library/SDK name (version optional), or
    • •The specific functions/classes/modules to cover
  • •Target audience (beginner vs experienced) and target language/runtime (Python/JS/etc.)
  • •Execution environment assumptions (OS, GPU/CPU, required services)
  • •Output directory (default: <workspace>/tmp/tutorials/<tutorial-name>; if the user specifies a dir, prefer the user-provided one)
  • •Any constraints (no network, no secrets, offline-only, time budget, etc.)

Outputs (what to produce)

Default output directory:

  • •<workspace>/tmp/tutorials/<tutorial-name>

Create the output directory with:

  • •tut-<what>.md
  • •scripts/ (end-to-end runnable scripts for this tutorial)
  • •inputs/ (small tutorial-specific inputs, if applicable)
  • •outputs/ (tutorial-specific outputs, if applicable)

In tut-<what>.md, include a YAML front matter block that records the runtime environment at the time the tutorial is created, including the base git commit hash of the workspace/repo.

Always provide end-to-end runnable scripts under scripts/ and have the tutorial instruct users to run those scripts (instead of embedding long code blocks in the doc).

Workflow

1) Identify the canonical sources

  • •Determine the authoritative docs/repo for the target API/library.
  • •Do not pin versions unless the user asks for it.
  • •If the tutorial is for a set of functions/classes in a local repo, read the source and identify:
    • •Import paths, initialization patterns, and required config
    • •Any side effects (I/O, network calls, GPU usage)

2) Choose a minimal “happy path”

  • •Define the smallest end-to-end example that demonstrates value:
    • •Inputs → processing → outputs
  • •Prefer real inputs if available; otherwise synthesize minimal inputs that satisfy the API contract.
  • •Record the exact commands used to run the example and the resulting artifacts.

3) Implement end-to-end scripts in scripts/

  • •Create one or more runnable scripts under scripts/ that demonstrate the full “happy path”.
  • •Scripts must:
    • •Read inputs from inputs/ (prefer real files; synthesize only if necessary and explain why)
    • •Write artifacts to outputs/
    • •Print a concise success summary (paths written, key shapes/counts)
  • •Keep scripts as small as practical but runnable; prefer a single scripts/run.py unless multiple steps are clearer.

4) Write tut-<what>.md (tutorial doc)

Choose a short, specific <what> (e.g., tut-httpx-basics.md, tut-onnxruntime-infer.md).

Follow the template in templates/tut-what.md:

  • •Start with a concrete Question (“How do I … using …?”).
  • •Add a Prerequisites checklist (do not teach setup in detail; assume prerequisites are already met).
  • •Add an Implementation Idea section with a short, high-level approach.
  • •Add Critical Example Code that is copy/pasteable and heavily commented to explain the usage step-by-step.
  • •Add Input and Output sections documenting the contract and showing representative examples (requests/responses, logs, artifacts).
  • •Keep code blocks self-contained and small; for the full implementation, point to scripts/... and show the exact command(s) to run.
  • •Add YAML front matter capturing:
    • •created_at (ISO8601), tutorial_name, topic
    • •base_commit (workspace git commit hash)
    • •runtime (OS, CPU/GPU, Python version, key package versions if relevant)

5) Include tutorial inputs/outputs

  • •Place tutorial-ready inputs under inputs/.
  • •Place tutorial outputs under outputs/.
  • •Keep them minimal and (when relevant) redistributable.

6) Add troubleshooting and verification

  • •Add a short “Troubleshooting” section with the top failure modes:
    • •Missing deps, version mismatches, device selection issues, path errors
  • •Add a “Verification” section:
    • •Exactly how to confirm outputs are correct (shapes, counts, sample prints, checksums)

Guardrails

  • •Do not include secrets/tokens or require users to paste credentials into the tutorial.
  • •Avoid “works on my machine” ambiguity: always include the exact commands and expected outputs/paths.
  • •Prefer stable, minimal dependencies; if multiple installation methods exist, pick one and mention alternatives briefly.