python-authoring skill
✓ VerifiedWrite, refactor, and review Python 3.12 code following strict stdlib-first, type-safe, and succinct development conventions.
- GitHub stars
- 19
- Files
- 1
- Last commit
- Nov 12, 2026
- License
- MIT
- Allowed tools
- —
What does the python-authoring skill do?
python-authoring is an agent skill. Write, refactor, and review Python 3.12 code following strict stdlib-first, type-safe, and succinct development conventions.
Summary generated from the skill's SKILL.md.
About the python-authoring skill
Developers looking to maintain high-quality Python 3.12 codebases can use this skill to write, refactor, or review code following strict architectural patterns. It is designed for working within specific directory structures like src/, scripts/, or tests/ to ensure all changes remain traceable and succinct. The skill prioritizes a standard library-first approach, meaning it favors built-in modules like argparse, pathlib, and json over adding new third-party dependencies.
When an agent loads this skill, it follows a rigorous workflow that includes validating untrusted input at boundaries and converting it into frozen dataclasses or domain types. It relies on specific tooling to ensure code quality, requiring the use of basedpyright for type-checking and just commands for validation. Users can trigger processes like just wedge-build to manage bundled archives or just check to run the final project gate. This ensures that every modification is type-safe, adheres to the existing dependency budget, and meets the repository's strict linting and testing standards.
What an agent can do with it
- 1Refactor existing Python logicUpdate Python code to be more succinct and use modern 3.12 features like match statements.
- 2Implement type-safe data validationCreate a boundary parser that converts raw input into validated, frozen dataclasses.
- 3Verify code quality and typesRun a full suite of type-checks and repository validations to ensure zero errors.
- 4Manage bundled Python archivesRebuild and verify Python .pyz packages after making changes to the source code.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the python-authoring skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the python-authoring skill in Claude Code
~/.claude/skills/python-authoring/SKILL.md
$ npx degit paulnsorensen/easy-cheese/.agents/skills/python-authoring ~/.claude/skills/python-authoringInstall the python-authoring skill in Claude Code (project)
.claude/skills/python-authoring/SKILL.md
$ npx degit paulnsorensen/easy-cheese/.agents/skills/python-authoring .claude/skills/python-authoringInstall the python-authoring skill in Codex
~/.agents/skills/python-authoring/SKILL.md
$ npx degit paulnsorensen/easy-cheese/.agents/skills/python-authoring ~/.agents/skills/python-authoringInstall the python-authoring skill in Gemini CLI
~/.gemini/skills/python-authoring/SKILL.md
$ npx degit paulnsorensen/easy-cheese/.agents/skills/python-authoring ~/.gemini/skills/python-authoringInstall the python-authoring skill in Claude.ai
npx degit paulnsorensen/easy-cheese/.agents/skills/python-authoring python-authoring && zip -r python-authoring.zip python-authoring # claude.ai → Customize → Skills → + → Create skill → Upload a skill → python-authoring.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablepaulnsorensen/easy-cheese/.agents/skills/python-authoring is public and reachablegithub.com/paulnsorensen/easy-cheese/tree/HEAD/.agents/skill ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-12github.com/paulnsorensen/easy-cheese/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/paulnsorensen/easy-cheese/blob/HEAD/.agents/skill ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/paulnsorensen/easy-cheese/blob/HEAD/.agents/skill ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 101 linesgithub.com/paulnsorensen/easy-cheese/blob/HEAD/.agents/skill ↗Pass
SKILL.md
View on GitHubAuthoring Python
Produce the smallest readable Python change that satisfies the request and matches easy-cheese.
This is a repository-local skill. Keep it under .agents/skills/python-authoring/; do not mirror it into the published skills/ tree or add agents/openai.yaml. Renaming this directory requires updating the matching !.agents/skills/<dir>/ line in .gitignore — that path list is an allowlist, so a renamed dir without its own line is silently untracked.
Work in this order
- Read the root configuration, owning skill, target exports, immediate callers, and nearby conventions.
- Keep every changed line traceable to the request. Do not invent orchestration, compatibility layers, abstractions, dependencies, or future flexibility.
- Put code in the owning package and preserve the bundle boundary.
- Validate untrusted input once at the boundary, then work with typed trusted data.
- Choose the clearest succinct Python construct; do not compress code until it becomes harder to read.
- Remove only slop introduced by the change and code that the change orphaned.
- Type-check changed files with basedpyright, run targeted tests, rebuild affected bundles, then run
just check.
Keep runtime code stdlib-first
- Target Python 3.12. Use its language and typing features directly; do not add compatibility code for older versions.
- Treat the standard library as the default dependency budget for bundled helpers under
src/. Any third-party runtime dependency must be pure Python and admitted torequirements/runtime.txt; bundle builds resolve internal and external hashes into an ephemeral requirements file. - Reuse the existing JSON-first, optional-YAML manifest boundary instead of importing PyYAML into new bundled modules.
- Treat configured third-party imports as surface-specific exceptions: PyYAML for existing validators, docs tooling, and manifest/test paths; pytest for tests. A new dependency requires an explicit package and CI decision.
- Prefer
argparse,json,pathlib,tempfile,shutil,zipfile,collections,itertools, andcontextlibover hand-written equivalents.
Model and validate data explicitly
- Parse untrusted text with the appropriate stdlib parser, require the expected container shape, check required keys and value types, and raise a specific error at the boundary.
- Convert validated mappings into frozen dataclasses or domain value types when named fields and invariants make the contract clearer.
- Use
TypedDictonly when a mapping must remain a mapping. It documents a static shape; it does not validate runtime input. - Use
EnumorLiteralfor closed value sets andProtocolfor structural interfaces that have multiple real consumers. - Fully annotate function and public-method boundaries. Omit obvious local annotations when inference is clear.
- Do not pass raw structured dictionaries beyond the parsing boundary when a named record makes the contract clearer.
Preserve skill package boundaries
- Keep skill runtime under
src/easy_cheese/skills/<skill_name>/and declare its CLI surface incommands.py. - Move code to
src/easy_cheese/shared/only when multiple existing skills need the same behavior; bundle it into each owning archive. - Do not import another skill's internals. Each archive carries its complete pure-Python runtime closure.
- Keep cross-skill orchestration in the owning workflow seam, not a leaf helper. Communicate through public or persisted contracts to avoid reverse dependencies and cycles.
- Never edit
skills/<skill>/scripts/<skill>.pyzby hand. Runjust wedge-buildafter changing archive inputs andjust wedge-checkto verify committed archives. - Keep CLI modules thin: accept
argv, return an integer status, print diagnostics to stderr, and propagate failure through a nonzero exit. - Keep
.github/scripts/validators read-only. They inspect and report; they do not mutate the workspace.
Prefer succinct, readable Python
- Use
matchfor genuine shape-based dispatch; keep a simpleiffor a binary decision. - Use a handler mapping for stable command-to-function dispatch; do not create a registry for one or two branches.
- Use an assignment expression only when it removes a repeated computation or clarifies a loop condition.
- Use
any,all, comprehensions, and generator expressions for pure collection queries or transformations. Keep a loop when it carries state, side effects, or clearer early exits. - Prefer generators when the result is consumed once.
- Use
enumerate, direct iteration, f-strings, context managers, andpathlibinstead of manual indexing, string assembly, cleanup, or path manipulation. - Ignore only named, intentional failures. Never use a bare
except, swallowException, return an empty default on failure, or usecontextlib.suppress(Exception). - Keep new top-level functions at 40 lines or fewer unless one contiguous algorithm is clearer than an artificial split.
- Prefer one clear expression to verbose scaffolding, but split dense expressions when intermediate names explain intent.
De-slop before finishing
- Delete narration comments and docstrings that restate the code. Keep non-obvious rationale and public API documentation.
- Remove abstractions with one concrete consumer unless the current task requires the seam.
- Name values after domain concepts, not containers or implementation types.
- Consolidate repetitive tests by behavior; do not add shallow input-variation tests.
- Fix the underlying lint issue instead of adding a suppression.
Type-check with basedpyright
- Run
basedpyright <changed .py files>(fall back touvx basedpyrightif the binary is absent) before finishing. Changed files must report zero errors and warnings. - Repo config lives in
[tool.basedpyright]inpyproject.toml: include paths,pythonVersion = "3.12", and an execution environment pinningsrc/easy_cheese_schemasto 3.11 to honor the published wheel'srequires-python >=3.11.typeCheckingModeis deliberately unset — basedpyright defaults torecommended, which enables every rule with an error/warning split andfailOnWarnings, so a full run fails on warnings too. - The whole repo is basedpyright-clean and
just typecheck(wired intojust check,just ci, and the validate workflow) enforces zero errors and warnings. Any diagnostic your change surfaces is yours to fix before finishing — there is no baseline and no pre-existing backlog to defer to. Imports resolve against.venv-typing;just typecheck-install(re)creates it fromrequirements/typing.txt. - basedpyright is stricter than stock pyright; its extra rules are binding here: assign deliberately ignored call results to
_(reportUnusedCallResult), collapse implicit string concatenations, andcastuntrusted boundary reads to their validated type. - Load build-only modules that are excluded from wheels with
importlib.import_modulepluscast-typedgetattr, not static imports the checker cannot resolve. - Fix the type at its source. When a suppression is genuinely unavoidable, use rule-scoped
# pyright: ignore[ruleName], never a bare# type: ignoreor a file-wide switch —reportIgnoreCommentWithoutRuleflags unscoped ignores. - Use
--outputjsonwhen a tool needs machine-readable diagnostics. In GitHub Actions the CLI detects CI and emits inline PR annotations with no extra flags. - Read exit codes precisely: 0 clean, 1 diagnostics reported, 2 fatal internal error, 3 unreadable config, 4 bad CLI arguments. Treat 2–4 as tooling breakage to fix or report, never as type findings.
- The binary is mise-managed and pinned to an exact version (upstream recommends exact pinning for reproducibility); the
pyrightandpyright-langservershims resolve to basedpyright.
Test and finish
- Test observable behavior and the reason it matters; do not add assertions that can pass when the implementation is broken.
- Keep filesystem tests inside
tmp_pathor an equivalent temporary directory. Do not depend on user paths, repository-external state, network access, or auto-loaded pytest plugins. - Run the most focused affected tests first. Focused pytest and browser commands execute committed
skills/<skill>/scripts/<skill>.pyzarchives without rebuilding them. Keep repository imports unavailable when testing archive isolation. - After archive inputs change, run
just wedge-build, thenjust wedge-checkbefore focused tests execute an archive. Runjust update-generatedwhen generated runtime sources change. - Run
just checkas the final project gate.
Completion check
Confirm:
- Runtime imports obey the stdlib-first, surface-specific dependency policy.
- Boundary input is validated once and converted into an appropriate trusted representation.
- Code lives in the owning skill source or a justified shared module.
- Command registration, generated runtime sources, and committed archives match their inputs when applicable (
scripts/runtime_gates.py,just wedge-check). - CLI and validator failures remain loud, read-only validators remain read-only, and tests are hermetic.
- No silent failures, speculative abstractions, narration comments, unnecessary local annotations, or unrelated cleanup remain.
- Changed Python files pass basedpyright with zero errors and warnings.
- A fresh
just checkrun passed.
Files in this skill
1python-authoring skill questions
How do I install the python-authoring skill in Claude Code?
Run npx degit paulnsorensen/easy-cheese/.agents/skills/python-authoring ~/.claude/skills/python-authoring. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the python-authoring skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What version of Python should I target?
You should target Python 3.12 and use its language and typing features directly without adding compatibility code for older versions.
How should I handle third-party dependencies?
The standard library should be the default dependency budget. Any third-party runtime dependency must be pure Python and added to requirements/runtime.txt.
How do I ensure my code passes type checking?
Run basedpyright on the changed files; they must report zero errors and warnings to be considered complete.