同名项目污染：pip 装到 ivanzwb / 国外多个同名 repo

你会遇到什么

按搜索资料执行 pip install agent-skills，结果装到无关同名项目；或 clone 到了 jdrhyne/tristanmanchester/AkshitIreddy/mikeng-io/callstackincubator 等同名仓库，命令、产物全对不上。同名污染把你带沟里了。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

• PyPI 存在 ivanzwb 同名包（CSDN 案例）；
• GitHub 存在 5 个以上同名 repo（国外信号）；
• 正确仓库 = addyosmani/agent-skills（manifest 签名），无 pip 分发，安装路径只有 npx/codeload 两条。

同名污染的本质是“名字不是有效身份”：任何分发渠道（PyPI/GitHub/npm）都只保证“这个名字在这个渠道唯一”，不保证“这个名字只属于一个项目”。所以同一个名字可以在 PyPI、GitHub、npm 上分别指向完全不同的项目——搜索引擎把三者混在一起给你，谁排前面取决于 SEO 而不是身份。

判断身份只能靠渠道内的权威锚点：GitHub 用组织名（addyosmani 是作者本尊，manifest 签名确认）；PyPI 用包名归属（agent-skills 在 PyPI 上属于 ivanzwb，而本项目没有 pip 分发——一个项目“有没有某个渠道的分发”本身就是身份信息）。

所以安装路径固定：本项目只有 npx/codeload 两条官方路径，任何教程让你 pip install 或 clone 其它仓库，都是污染源。

已装错时的清理也走固定顺序：pip show/pip uninstall 清 PyPI 同名包 → 检查 ~/.claude/skills/ 下多余目录 → 用官方路径重装。

一步步来

1. 认准仓库与安装路径 — 必做

npx skills add addyosmani/agent-skills

或 codeload：curl -sL https://gh-proxy.com/https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz。

2. 检查是否已装错 — 排查

pip show agent-skills 2>/dev/null && pip uninstall agent-skills

如果 pip 里有这个包，就是装到 ivanzwb 了，卸载掉。

3. 清理错误技能目录 — 必做

检查 ~/.claude/skills/ 下非本条目的目录（来自同名仓库的复制产物），确认后删除。

怎么确认修好了

正确的技能目录存在（实测形态）：

ls ~/.claude/skills/agent-skills
→ 24 个子目录，每个含 SKILL.md

pip list | grep agent-skills 无输出（不再有 ivanzwb 包）。

其它环境的表现

症状

按搜索资料执行 pip install agent-skills 装到无关同名项目；或 clone 到 jdrhyne/tristanmanchester/AkshitIreddy/mikeng-io/callstackincubator 等同名仓库，命令/产物对不上。

原因

PyPI 存在 ivanzwb 同名包（CSDN 案例）；GitHub 存在 5 个以上同名 repo（国外信号）；正确仓库 = addyosmani/agent-skills（manifest 签名），无 pip 分发，安装路径只有 npx/codeload。

解法

1. 认准仓库与安装路径：npx skills add addyosmani/agent-skills 或 codeload addyosmani/agent-skills tag tarball；不要 pip install。
2. 已装错时卸载 pip 包并清理对应技能目录（~/.claude/skills 下非本条目目录）。