MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-write-pypi-skill
pywf-oss-write-pypi-skill
VerifiedGenerate an Agent Skill, named pypi-<package_name>, that documents this library's public API and command line interface, so future sessions in other projects can use the library without re-reading its source. Use when the user asks to turn this library into a Claude skill, usually after a release.
Generate an Agent Skill that lets future sessions use this library through its public API, without loading the source.
Read ../pywf-oss-base/SKILL.md, then:
- ../pywf-oss-base/references/08-package-files.md (
api.pydefines the public API;cli.pyis the python-fire CLI) - ../pywf-oss-base/references/18-knowledge-channels.md (what goes in this skill, and what does not)
Where to write the output
Write to .claude/skills/<skill_name>/ in this repo, and commit it: the skill ships with the source, and the README tells users how to copy it into their own projects (Step 6). It documents how to use the library; how to maintain it belongs to the <maintain_prefix> family, never here. Never write to ~/.claude/skills/ unless the user asks. If the target directory exists, ask before overwriting.
Step 1: Inspect the project
From pyproject.toml at the working-directory root, take:
[project].name:<package_name>. The skill's name ispypi-<package_name>, called<skill_name>below: thepypi-prefix marks it as the API reference of an installed library, and keeps it apart from the package name and from thepywf-oss-*skills. It is both the folder name and the frontmattername.[project].version: for the skill header.[project.scripts], if present: the CLI entry point (such as<cli_name> = "<package_name>.cli:main") and its executable name, the key.
Step 2: Walk the public API
Read <package_name>/api.py top to bottom: each from ... import X line is one public symbol. For each, open its defining module:
- Constant or function: signature, docstring, and return value.
- Class or dataclass: also every non-underscore method and property, each with its signature and a one-line summary, and a dataclass's fields.
- Subpackage API (
from .subpackage import api as subpackage): recurse into itsapi.pywith the same rules. Users refer to its symbols assubpackage.ClassName.
Skip every name starting with _. Document only the two canonical import forms:
from <package_name>.api import X
import <package_name>.api as <package_name> # then <package_name>.X
Step 3: Take usage examples from tests/
Grep tests/ for each public symbol. The shortest passing test that exercises it is usually the cleanest example: trim it to the essentials, never paste whole test files.
Step 4: Inspect the CLI (only when [project.scripts] exists)
Read the entry-point module, and walk the whole command tree: every subcommand, flag, and default. All of it goes into ref/cli.md.
Step 5: Write the skill
<base>/<skill_name>/
├── SKILL.md
└── ref/
├── public-api.md
└── cli.md # only if the library has a CLI
SKILL.md: overview, always loaded
It must suffice for common tasks without ref/, in 50 to 150 lines:
- Frontmatter
name:<skill_name>. - Frontmatter
description: the library name, what it does in one sentence, and its top public symbols, so the skill surfaces on matching requests. - Purpose: one paragraph.
- Import: the two canonical forms above, nothing else.
- Public API: a flat list, one entry per symbol: a function or method with its typed signature and a one-line summary; a dataclass with its fields and summary, then its method and property signatures, one per line; a constant with its value or type and summary.
- CLI (only if any): one short paragraph. The command is usually
.venv/bin/<cli_name>,<cli_name> -hlists the subcommands, andref/cli.mdhas every argument. Do not list subcommands here: CLI use is rare, so its detail loads lazily. - More detail: "For full API docs see
ref/public-api.md. For full CLI args seeref/cli.md."
ref/public-api.md: full API reference, loaded on demand
Written for an engineer using the library, not maintaining it. For each public symbol: the full typed signature; parameter and return semantics, with the why only when non-obvious (invariants, gotchas, constraints the caller must respect); and a short usage example, preferably trimmed from tests/. No walkthroughs of internal code.
ref/cli.md: full CLI reference, loaded on demand
It loads when the user mentions the CLI, so it must make --help unnecessary: for each subcommand, a short description, every flag with type and default (a small table reads well), and one short example. Complete, not verbose.
Step 6: Mention it in the README
If README.rst has no such section yet, add one after the install section, so users know the skill exists and how to get it. <repo_url> is [project.urls].Repository in pyproject.toml; <repo_dir> is its last path part.
.. _use-with-ai-coding-agents:
Use with AI Coding Agents
------------------------------------------------------------------------------
This repo ships an `Agent Skill <https://code.claude.com/docs/en/skills>`_ that documents the public API of ``<package_name>``, so an AI coding agent such as Claude Code can use the library without reading its source. It lives in `.claude/skills/<skill_name> <<repo_url>/tree/main/.claude/skills/<skill_name>>`_. To use it in your project, copy it into your project's ``.claude/skills/`` folder. Run this from your project's root:
.. code-block:: console
$ git clone --depth 1 <repo_url>.git /tmp/<repo_dir>
$ mkdir -p .claude/skills
$ cp -R /tmp/<repo_dir>/.claude/skills/<skill_name> .claude/skills/
Then check that it renders on PyPI: mise exec -- uvx --from readme-renderer python -m readme_renderer README.rst -o /dev/null.
Keep it short
Every line of SKILL.md stays in the conversation once the skill is invoked, so it costs tokens on every use. Prefer signatures, tables, and short examples to prose; the same holds, less strictly, for the lazily loaded ref/ files.
Verify before finishing
For 2 or 3 representative symbols, check that the import works:
.venv/bin/python -c "from <package_name>.api import ClassName"
If one fails, the docs are wrong. Fix them before reporting done.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |