python-packaging

python-packaging 技能概览

python-packaging 技能适合做什么

python-packaging 技能用于帮助代理把一个 Python 代码库整理成可分发的包，包括正确的项目结构、打包元数据、构建配置以及发布流程。它面向的不只是“让这个项目可以安装”这种基础需求，而是希望产出符合现代 Python 打包标准的结果，尤其适用于 pyproject.toml、wheel、source distribution，以及面向 PyPI 风格发布的场景。

哪些人适合使用 python-packaging 技能

如果你正在做以下事情，python-packaging 技能会非常合适：

• 打包一个可复用的库
• 发布带 console entry points 的 CLI 工具
• 为项目准备发布到 PyPI 或私有包索引
• 从临时脚本或旧式 setup.py 模式迁移
• 在 setuptools、hatchling、flit 或 Poetry 打包方案之间做选择

如果你的项目只是内部脚本仓库，既不需要安装也不需要分发，那这个技能的价值就相对有限。

真正需要解决的任务是什么

大多数用户要的并不只是“生成几个文件”。他们真正想尽早做对的是一整套打包决策：目录布局、元数据、依赖声明、editable install、build backend、测试安装流程，以及最终的发布路径。python-packaging 技能的价值就在于，它会把这些选择明确展开，而不是把打包当成一次性吐出模板文件的动作。

它和通用打包提示词有什么区别

python-packaging 技能最大的优势在于决策覆盖面更完整。它不会停留在一个最小可用的 pyproject.toml，还会覆盖：

• 推荐的 src/ 目录布局
• 基于现代 PEP 的打包标准
• backend 选型的取舍
• wheel 与 source distribution 的差异
• 包元数据与 classifiers
• CLI 的 entry points
• package data、namespace packages 等进阶模式

因此，和普通“帮我创建 Python package 文件”的提示词相比，它更适合面向 Deployment 的实际工作。

安装前建议先确认什么

在决定使用 python-packaging 技能前，建议先确认你能回答这些基础问题：

• 这是一个库、CLI、插件，还是 namespace package？
• 你需要发布到 PyPI，还是只做内部分发？
• 你现在是否已经在用 Poetry 或其他工具管理依赖？
• 你是否需要 package data、typed packages 或编译扩展？
• 你只面向现代打包流程，还是还要兼容旧工作流？

如果这些问题你现在还没完全想清楚，这个技能依然能帮上忙；但最终结果的质量会很大程度取决于你提供输入的清晰度。

如何使用 python-packaging 技能

安装 python-packaging 技能

通过仓库安装：

npx skills add https://github.com/wshobson/agents --skill python-packaging

如果你的环境里已经本地拉取了该仓库，请确认可以从 plugins/python-development/skills/python-packaging 访问到这个技能。

先读这两个文件

使用这个 python-packaging skill 时，建议先看：

• SKILL.md
• references/advanced-patterns.md

SKILL.md 讲的是核心工作流和工具选型。若你的项目涉及数据文件、namespace packages、更完整的发布配置，或超出基础包骨架的安装测试，那么 references/advanced-patterns.md 就尤其重要。

明确这个技能需要什么输入

python-packaging usage 的效果高度依赖具体仓库上下文。最好给代理这些信息：

• package name
• import name
• 项目类型：library、CLI、plugin、internal package
• 目标 Python 版本
• 希望使用的 build backend
• 依赖分组：runtime、optional、dev
• 是否希望采用 src/ 布局
• 是否会发布到 PyPI、TestPyPI 或私有索引
• 是否需要 console scripts、data files 或 namespace packaging

如果没有这些信息，代理依然可以搭一个骨架，但很可能会选错 backend，或者把元数据结构做偏。

把模糊目标改写成高质量提示词

较弱的提示词：

Package this Python project for release.

更好的提示词：

Use the python-packaging skill to convert this repo into a distributable package. Use a src layout, setuptools with pyproject.toml, Python 3.10+, one console entry point named my-tool, optional dev dependencies for pytest and ruff, and prepare for publishing to PyPI. Show the exact files to add or change and explain any assumptions.

为什么这个版本更好：

• 明确了打包方式
• 指定了 backend 和最低 Python 版本
• 包含了 CLI 需求
• 说明了依赖分组
• 设定了发布目标
• 要求给出文件级改动，而不是泛泛建议

有意识地选择合适的 backend

一份实用的 python-packaging guide 不应该把不同 build backend 当成可以随便互换。

可以用这个技能来做明确选型：

• setuptools：最稳妥的默认选项，生态兼容性广
• hatchling：如果你想减少历史包袱，它是更干净的现代默认方案
• flit：适合简单的纯 Python 库
• Poetry：如果你本来就依赖 Poetry 工作流会很合适；但如果你只是需要打包功能，它可能显得过于强约束

如果你自己没有明确偏好，可以直接让代理基于仓库形态推荐一种，并说明理由。

除非有明确理由，否则优先用 src 布局

这个技能会明显倾向于 src/package_name/，而对可安装包来说，这通常也是更稳妥的决定。它能减少从仓库根目录意外导入模块的问题，也更容易提前暴露打包错误。

只有在你明确想保留一个更轻量、偏本地使用的结构，并且清楚知道代价时，才建议要求 flat layout。

把这个技能用于 Deployment，而不只是搭骨架

python-packaging for Deployment 才是这个技能比普通提示词更有价值的地方。建议让它覆盖完整路径：

1. 在 pyproject.toml 中定义元数据
2. 构建 wheel 和 source distribution
3. 在干净环境中安装构建产物
4. 验证 entry points 和 imports
5. 准备发布到 PyPI 或内部索引的上传步骤

如果你只是让它生成模板文件，就会错过那些真正拖慢发布进度的质量检查环节。

明确要求安装测试

一个很常见的打包误区是：只因为在仓库内 import 成功，就以为包已经可用。使用这个技能时，应该明确要求生成类似下面的验证步骤：

• build distributions
• 创建全新的 virtual environment
• 安装 wheel
• 运行 import smoke tests
• 执行 CLI entry point

这能在发布前提前发现 package data 缺失、entry point 声明错误、目录布局错误等问题。

只有在仓库确实需要时才用进阶模式

如果你的项目需要以下能力，再去读 references/advanced-patterns.md：

• 需要一起打包的 data files，例如 JSON、templates 或静态资源
• py.typed 支持
• 跨多个仓库拆分的 namespace packages
• 更复杂的版本管理或分发模式

不要默认让代理把这些都加进去。它们会增加复杂度，应当由真实项目需求驱动。

推荐的仓库阅读与决策流程

对于 python-packaging install 和初始化配置，一个实用的流程是：

1. 检查当前仓库布局
2. 识别 import package name 与 project name 是否不同
3. 决定 backend 和发布目标
4. 定义元数据与依赖
5. 按需添加 entry points 或 package data
6. 构建并测试 distribution
7. 复核发布步骤

这个顺序很重要，因为 backend 和布局选择会影响后面几乎所有文件。

一份高质量输出应该包含什么

一个好的 python-packaging skill 输出通常会包括：

• 更新后的或新建的 pyproject.toml
• 包目录结构
• 依赖声明
• build-system 配置
• 如有需要的 CLI entry points
• 如有需要的 package data 配置
• install/build/test 命令
• 面向所选索引的发布说明

如果输出只有一个很小的 pyproject.toml，却没有验证路径，那通常说明内容过浅。

python-packaging 技能常见问题

python-packaging 技能对新手友好吗？

友好，但前提是你已经知道这个项目最终要变成什么。对于同时不熟悉 Python 和打包概念的人来说，它并不算理想，因为 backend 选择、元数据和分发目标这些问题仍然需要你自己做决定。

它比普通的 Python 打包提示词更好吗？

通常是的。普通提示词往往只会生成一个泛化的 setup.py，或一个很薄的 pyproject.toml，却不解释背后的取舍。python-packaging skill 更适合那些需要一份真正贴合发布目标的打包方案的场景。

它支持现代 Python 打包吗？

支持。仓库内容明显以现代标准为中心，例如 pyproject.toml、PEP 517/518、PEP 621，以及像 PEP 660 这样的 editable install 概念。

如果我已经在用 Poetry，还应该用 python-packaging 吗？

可以，但要说清楚。如果“必须保留 Poetry”是硬性要求，就要明确告诉代理；否则它很可能会基于“只做打包”的需求，合理地建议改用其他 backend。

什么情况下不该使用 python-packaging 技能？

以下情况可以跳过它：

• 项目本来就不打算被安装
• 你只需要一个本地脚本目录
• 你需要的是超出该技能实际覆盖范围的、非常专门的编译扩展构建系统
• 你的组织已经强制规定了必须严格遵守的内部打包模板

它能处理 namespace packages 和 package data 吗？

可以。这恰恰是建议阅读高级参考文档的重要原因之一。这两类问题本来就是打包中的高频踩坑点，而这个技能提供的模式不止是最小起步配置。

如何提升 python-packaging 技能的使用效果

提供打包约束，不只说最终目标

想让 python-packaging 产出更靠谱，最好明确这些约束：

• 精确的 Python 支持范围
• 公共索引还是私有索引
• backend 偏好
• typed package 要求
• 是否必须包含 data files
• imports 是否必须保持向后兼容

这些信息对文件布局和元数据的影响，通常比多数用户预期更大。

给出当前仓库目录树

一份简短的目录树会明显提升输出质量。例如：

src/、tests/、现有的 requirements.txt、当前 CLI 模块，以及任何 assets 目录。这样代理就不容易误判 package 边界，也不容易漏掉非代码文件。

明确哪些内容必须保持稳定

很多打包改造都会不小心改坏 import path 或命令名。要提前告诉代理哪些不能动：

• package import name
• 现有 CLI 命令
• 当前版本管理策略
• CI 命令
• 发布流程要求

在从旧式打包文件迁移时，这一点尤其关键。

不只要生成文件，也要求说明理由

更好的提示词例如：

Use the python-packaging skill and explain why you chose setuptools over hatchling for this repo.

这样会迫使代理给出可审查的决策依据，而不是让你被动接受一个未必适合工作流的默认选择。

注意这些常见失败模式

最常见的低质量输出包括：

• 没必要地把旧式 setup.py 习惯和现代 pyproject.toml 混在一起
• 在更适合 src/ 的情况下仍选择 flat layout
• 忘记包含 package data
• project name 和 import package name 对不上
• 定义了 console scripts，却没有验证安装后的行为
• 给了发布步骤，却没有做干净环境安装测试

在真正实施前，建议优先检查这些问题。

第一版出来后继续迭代

拿到第一版结果后，可以继续用更明确的追问来细化：

• Convert this to hatchling.
• Add package data for templates and py.typed.
• Prepare this package for TestPyPI first.
• Keep the current import path but add a console script.
• Make this a namespace package across two repos.

当你把这个技能当成打包决策伙伴，而不是一次性文件生成器时，它会更有价值。

提升 python-packaging 在 Deployment 工作流中的价值

如果你的核心目标是提高发布就绪度，可以要求这个技能输出：

• build 命令
• 产物验证步骤
• 干净环境安装测试
• publish 命令
• rollback 或 version bump 指南

这样 python-packaging guide 才会真正变成可执行的 Deployment 方案，而不只是静态配置建议。

有选择地使用高级参考

references/advanced-patterns.md 最适合在基础配置已经明确之后再使用。先从简单方案开始，只引入那些确实能解决实际打包问题的高级模式。这样可以让最终包更容易维护，也能减少无意引入的复杂度。