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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.3 KB |
SKILL.md
View on GitHub---
name: pywf-oss-write-pypi-skill
description: "Generate 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.py` defines the public API; `cli.py` is 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 is `pypi-<package_name>`, called `<skill_name>` below: the `pypi-` prefix marks it as the API reference of an installed library, and keeps it apart from the package name and from the `pywf-oss-*` skills. It is both the folder name and the frontmatter `name`.
- `[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 its `api.py` with the same rules. Users refer to its symbols as `subpackage.ClassName`.
Skip every name starting with `_`. Document only the two canonical import forms:
```python
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> -h` lists the subcommands, and `ref/cli.md` has 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 see `ref/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.
```rst
.. _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:
```bash
.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: 471k | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |