Add portable Python best-practices AI skill

skills/python-best-practices/README.md

@@ -0,0 +1,33 @@
+# Python Best Practices — Portable AI Skill
+
+A single, tool-agnostic skill that teaches any AI IDE/agent to write modern,
+idiomatic **Python 3.10+**. The content lives in [`SKILL.md`](./SKILL.md) and is
+plain Markdown with YAML front matter, so it is readable by virtually every
+assistant.
+
+## What it covers
+
+Type hints (PEP 484/585/604), dataclasses & Pydantic v2, context managers,
+generators/iterators, the decorator pattern, async/await with asyncio,
+structural pattern matching (3.10+), the `src/` project layout, dependency
+management with **Poetry/uv**, and PEP 8 + **Black** + **Ruff** formatting/linting.
+
+## Use it in your tool
+
+The same `SKILL.md` works everywhere. Pick whichever wiring your tool expects:
+
+| Tool / Agent | How to enable |
+| --- | --- |
+| **Claude / Claude Code (Agent Skills)** | Place this folder under your skills dir (e.g. `.claude/skills/python-best-practices/`) — `SKILL.md` is auto-discovered via its front matter `name` + `description`. |
+| **Cursor** | Reference it from a rule, or add a `.cursor/rules/python-best-practices.mdc` that points to / inlines this file. You can also `@`-mention `SKILL.md` in chat. |
+| **GitHub Copilot** | Copy the body into `.github/copilot-instructions.md` (or link to it). |
+| **Windsurf / Codeium** | Add the body to `.windsurfrules`. |
+| **Cline / Aider / others** | Add `SKILL.md` to the project context or instruction file the agent reads. |
+| **Any agent** | Just feed `SKILL.md` as context — it's standard Markdown. |
+
+## Tips
+
+- If your repository already defines Python conventions, those win — this skill
+  is a sensible default, not a mandate.
+- Keep the front-matter `description` intact: skill-aware agents use it to decide
+  *when* to activate the skill automatically.