modern-python

modern-python skill 概览

modern-python 的作用

modern-python skill 可帮助你围绕 uv、ruff 和 ty 启动或现代化 Python 项目，而不是继续沿用 pip、Poetry、mypy、black 这类旧组合。它最适合你需要一份实用的 modern-python 指南，用于项目初始化、脚本打包或迁移工作，并且希望这些操作可重复、速度快、维护成本低。

适合哪些人使用

如果你要新建一个 package、创建 CLI、编写带依赖的单文件脚本，或把现有 repo 迁移到现代工具链，就适合使用 modern-python skill。对于使用 Python 3.11+、希望把安装、lint、格式化、测试和依赖管理统一到一条工具链上的团队，它尤其合适。

它为什么不同于通用提示词

这个 skill 不是简单一句“用 uv”。它内置了具体的决策规则：什么时候用 pyproject.toml，什么时候用 PEP 723 的脚本元数据，什么时候提交 uv.lock，以及什么时候不该替换现有工作流。正因如此，modern-python skill 比普通提示词更有用，因为它给模型的是明确约束，而不是模糊偏好。

如何使用 modern-python skill

安装并加载正确上下文

先用目录中常规的 skill 安装命令安装 modern-python skill，然后按顺序先读 SKILL.md，再读 references/pyproject.md、references/ruff-config.md 和 references/uv-commands.md。如果你是在做迁移，在开始修改前还要读 references/migration-checklist.md 和 references/testing.md。

给 skill 一个真实的项目形态

当你明确告诉它你在做什么时，modern-python 的效果最好：

• library、app 还是 CLI
• 单文件脚本还是多文件项目
• 全新 repo 还是迁移项目
• 现在是否必须保留旧工具

更好的请求方式像这样：“把这个 repo 设为使用 uv、ruff、ty 和 uv_build 的 Python 3.12 package；保持它适合做 library，添加 dev dependency groups，并避免使用 Poetry。” 这比直接说“给我现代 Python 最佳实践”更好，因为 skill 才能据此选择合适的文件和命令。

先读信号最强的文件

做安装导向的工作时，建议按下面顺序预览这些路径：

1. SKILL.md
2. references/pyproject.md
3. references/uv-commands.md
4. references/ruff-config.md
5. 如果任务是脚本，再看 references/pep723-scripts.md
6. 如果任务是迁移，再看 references/migration-checklist.md

如果你还需要 repo 脚手架或 CI 钩子，请把 templates/dependabot.yml 和 templates/pre-commit-config.yaml 作为实现锚点来检查。

用能减少猜测的信息

modern-python skill 最依赖清晰约束：Python 版本、目标 package 名称、是否应忽略 .venv/、是否要提交 uv.lock、以及哪些工具是必须的。如果你希望它帮你做迁移，也请写明当前技术栈，以及哪些部分必须保持不变，这样 skill 就能避免不必要地重写你的工作流。

modern-python skill 常见问题

modern-python 只适合新项目吗？

不。modern-python skill 也面向迁移，但前提是你确实希望把 repo 往 uv、ruff 和 ty 方向推进。如果项目必须保留现有工具，就应该选择性使用，甚至完全不用这个 skill。

什么时候该用 PEP 723，而不是 pyproject.toml？

当你面对的是一个带依赖的单文件工具时，用 modern-python skill 的脚本路径。若项目有多个文件、可复用代码，或者已经有明确的 package 边界，就用 pyproject.toml。这个边界本身，就是安装 modern-python skill 的主要理由之一。

这能替代普通提示词吗？

在你需要可重复的设置决策时，可以。普通提示词能描述工具，但 modern-python skill 提供的是一套关于依赖管理、lint、格式化和迁移取舍的指南，因此模型更不容易混用不兼容的模式。

它适合 Python 初学者吗？

适合，前提是你的目标是一个干净、现代的技术栈。如果你还在学习旧工具链的约定，或者需要支持 Python 3.11 以下版本，它就不那么合适，因为这个 skill 的设计默认基于 modern-python 假设。

如何改进 modern-python skill

先说明你最看重什么结果

想要更好的 modern-python 结果，就直接说你更在意哪一项：library 打包、脚本可移植性、CI 就绪度，还是迁移安全性。不同侧重点会改变输出：library 需要更严格的依赖管理和 lockfile 指南，而脚本可能更适合用 PEP 723 元数据，而不是完整的项目结构。

先把缺失的项目事实补齐

最常见的失败模式是安装或配置信息不完整。请提前提供：

• 目标 Python 版本
• package 名称和 import 名称
• 扁平布局还是 src/ 布局
• 是否提交 uv.lock
• 必需工具：ruff、ty、测试、pre-commit、Dependabot

这些信息能让 modern-python skill 产出可直接使用的安装方案，而不是泛泛建议。

先按 repo 规范检查第一版

拿到第一版输出后，检查它是否符合你 repo 对 dependency groups、formatter 设置和测试命令的约定。如果有偏差，用窄范围修正继续迭代，比如：“保留现有 CI，但只把 linting 和依赖管理替换成 modern-python 方案。”

注意常见的不匹配场景

当项目必须保留 pip/Poetry 语义、支持更旧的解释器，或者长期处于“半现代、半传统”的状态时，modern-python 的效果会变弱。在这些情况下，应该要求 skill 保守适配，而不是彻底重构整个技术栈；或者干脆不要在那个 repo 上使用它。