MacHu-GWU/sqlalchemy_upsert_kit-project / .claude/skills/pywf-oss-write-maintain-skill
pywf-oss-write-maintain-skill
VerifiedCreate or update this library's own maintenance skill family, maintain-<package_name>-base plus one invoker per repeatable job, that records its architecture, invariants, design decisions, debugging recipes, and library-specific jobs, so agents maintaining the repo need no maintainer guide. Use when the user asks to write down how to maintain the repo, to document architecture or a maintenance procedure, to move a maintainer guide out of the docs, or after a change that adds an invariant or a maintenance job.
Write maintenance knowledge where an agent working in this repo will load it: the <maintain_prefix> skill family (maintain-<package_name>), not a docs page that agents would never load.
Read ../pywf-oss-base/SKILL.md, then:
- ../pywf-oss-base/references/00-authoring-references.md (the base and invoker rules, file shape, script conventions)
- ../pywf-oss-base/references/07-repo-layout.md
- ../pywf-oss-base/references/18-knowledge-channels.md
Step 1: Decide what is new
- Read
[project].namefrompyproject.toml:<maintain_prefix>ismaintain-<package_name>. - List what exists:
.claude/skills/<maintain_prefix>-*/, and any maintainer pages underdocs/source/(such as a99-Maintainer-Guide/folder). - From the user's request, list the facts to record. Sort each with
18-knowledge-channels.mdsection 2. A user-facing fact goes topywf-oss-write-doc, a public-API fact topywf-oss-write-pypi-skill, and a template convention is already inpywf-oss-base: name the skill, and drop it here. - New family: propose the reference files (
NN-slug.md, lifecycle order) and any invokers, one line each, and wait for the user's yes before writing. The names end up in every relative path. - Existing family: say which files change and which are added.
Step 2: Gather facts from the code
Read the modules, tests, .mise/tasks/, and git history the facts are about. Every claim names its source file or function. Never invent a rationale: when the reason for a design is not in the code, the commit messages, or the user's words, ask the user.
Step 3: Write the base
.claude/skills/<maintain_prefix>-base/
├── SKILL.md
└── references/NN-slug.md
SKILL.mdfrontmatter:name: <maintain_prefix>-base, and a double-quoteddescriptionnaming this library and the kinds of knowledge it holds, so it loads when someone changes the repo.SKILL.mdbody: one paragraph on the library's architecture; "For template conventions, loadpywf-oss-base"; the references index between the same markers as inpywf-oss-base; and, once there are invokers, which one does which job.- References follow
00-authoring-references.mdsections 2 and 3, with one difference: they are about this one library, so they use its real module and class names instead of placeholders. - Scripts, if any, follow
00-authoring-references.mdsection 4, and are added to theformatandlinttask paths inmise.toml.
Step 4: Write the invokers (only for repeatable jobs)
Each .claude/skills/<maintain_prefix>-<action>/SKILL.md does one job: what it does, "Read ../<maintain_prefix>-base/SKILL.md, then:" with the files it needs, its steps, where it stops for the user's yes, and what it reports. A step that is a template convention cites the pywf-oss-* skill or reference by name instead of restating it.
Step 5: Move a maintainer guide out of the docs
If docs/source/ holds maintainer pages, carry their facts into the family, still true against the code. Then show the user the pages to delete, and delete them only after the user's yes. The docs keep user-facing pages only.
Step 6: Verify
python ${CLAUDE_SKILL_DIR}/../pywf-oss-base/scripts/update_skill_index.py --skill_dir .claude/skills/<maintain_prefix>-base
python ${CLAUDE_SKILL_DIR}/../pywf-oss-base/scripts/check_skill_family.py --skills_dir .claude/skills --prefix <maintain_prefix>
Both report 0 problems. If a script was added, mise run format, then mise run lint, reports nothing. If docs pages were removed, mise run build-doc shows no new warnings.
Output
Show the family's tree, each invoker with the base files it reads, and the facts that were left out because they belong to another channel.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |