Claude Code 与 Codex Agent Skills 推荐：值得装哪些、安装前怎么审计、新 Skill 不触发怎么办

Name

Soren Atelier

更新于 2026/11/15

先说结论：装几个 Skill 就够，不要把整个仓库都装进来。三条规则：

1. 按用途挑。先装一个小的纯文本包，比如 obra/superpowers（15 个 Skill），或者单个 Skill，比如 Jane Street 的 socratic-tutor。google/skills（203 个）和 NVIDIA/skills（452 个）这类大目录先别动，等你需要其中某一个 Skill 时再单独装。
2. 先读再装。一个 Skill 就是一段指令加上可选的脚本，脚本以你的 Agent 的权限运行。下文第 1 步的审计脚本会列出哪些 Skill 自带代码、哪些文件该先打开看。它只读文件，不执行任何东西。
3. 装完检查列表。Claude Code 会把一份 Skill 名称和描述的列表交给模型，这份列表有上限。在一台已经装了 98 个 Skill 的机器上，新装的 Skill 只列出了名称，模型手里没有描述，无从匹配你的请求。先运行 /skill-doctor，再用 skillOverrides 腾出预算，或者用 skillListingBudgetFraction 调高预算。

实测范围：文中所有数字都来自 2026 年 11 月 15 日的浅克隆，以及 macOS 上的 Claude Code 2.1.325。审计脚本、claude plugin validate、/skill-doctor 和调试日志都实际运行过。模型之后会不会自己选中某个 Skill，没有测试；SkillSpector、npx skills 安装器和 Codex 也没有测试。文末的「实测 vs 文档」表格把两者分开列出。

10 个 Skill 仓库对比

Agent Skill 是带有 SKILL.md 文件的文件夹，Claude Code、Codex 和其他 Agent 会按需加载。如果你想了解格式本身，Codex vs Claude Code Skills 讲了路径、frontmatter，以及怎么让两个工具共用同一个 Skill。本文讲的是怎么挑选和安装别人写好的 Skill。

11 月初，Skill 仓库的关注度突然上升。Jane Street 在 11 月 3 日发布了一个只有单个 Skill 的仓库，在 Hacker News 上拿到 712 分。GoogleChrome/modern-web-guidance 在 11 月 10 日发布了 1.0.0。anthropics/skills 一周内涨了约 6,200 个 star。

下表统计了每个仓库里的全部 SKILL.md。「描述字符数」是 description 文本的总长度，也就是 Agent 每一轮都要为每个 Skill 加载的内容。最后一列把它和测试机器上 Claude Code 报告的 30,000 字符列表预算做了对比。

有三点值得注意。

• 规模相差两个数量级。把 google/skills 或 NVIDIA/skills 整个装上，列表会超出预算好几倍。两个仓库的 README 都支持只装单个 Skill：NVIDIA 用 --skill，Google 在安装器的提示里选择。
• 大多数 Skill 是纯 Markdown。782 个 Skill 里有 552 个完全不带代码。带代码的集中在文档、媒体和云服务类 Skill 上，由脚本负责确定性的那部分工作。
• 预先批准工具的情况很少，只集中在一个目录里。NVIDIA/skills 有 126 个 Skill、google/skills 有 2 个 Skill 声明了 allowed-tools。其余八个仓库都没有。

哪个仓库适合哪种用途

• obra/superpowers 是一套完整的工作方法：头脑风暴、写计划、执行计划、系统化调试、确认无误后才说完成。按上下文开销算，它是大型包里最省的。
• addyosmani/agent-skills 更像一组工程检查清单：代码评审、API 设计、CI、可观测性、安全加固。它的描述更长，所以 25 个 Skill 的开销大约是 Superpowers 的四倍。
• mattpocock/skills 偏向由你自己调用的短命令（/grill-me、/tdd、/to-spec）。里面有八个 in-progress 状态的 Skill。
• anthropics/skills 是参考实现。做数据的人通常想要其中的 xlsx、pdf、docx 和 pptx，这几个 Skill 自带真正生成文件的脚本。如果你的分析都在 notebook 里，像 RunCell (opens in a new tab) 这样直接在 Jupyter 里工作的 Agent，可以补上这些文件类 Skill 管不到的部分。
• GoogleChrome/modern-web-guidance 只有两个 Skill，背后是一个检索指南索引的 CLI，目的是让 Agent 别再用过时的前端写法。
• kajisho5/ffmpeg-skill 是一个带 107 个代码文件的大型 Skill，在仓库里有两处镜像，另外 .claude/skills 下还有 14 个作者自己的项目 Skill。请用它自带的安装器安装，不要直接复制整个仓库。

第 1 步：安装前先审计 Skill 仓库

Skill 的指令会进入 Agent 的上下文，它的脚本以你当前会话的权限运行。唯一的防线就是先把仓库读一遍，所以要让这件事做起来够快。

下面这个脚本会遍历一个文件夹，找出所有 SKILL.md，然后打印哪些 Skill 自带代码、哪些包含值得一看的模式。它只用 Python 标准库，并且绝不运行被扫描文件夹里的任何东西。

#!/usr/bin/env python3
"""Read-only audit of SKILL.md folders. Runs nothing from the repo it scans."""
import os, re, sys
 
RISKY = {
    "pipe-to-shell": r"(curl|wget)[^\n|]*\|\s*(sudo\s+)?(ba|z)?sh",
    "reads-secrets": r"\.ssh/|\.aws/credentials|\.env\b|id_rsa|\.netrc|keychain",
    "sudo": r"\bsudo\s",
    "rm-rf": r"\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r",
    "skip-permissions": r"dangerously-skip-permissions|bypassPermissions|--yolo",
    "hidden-unicode": r"[\u200b\u200c\u200d\u2060\u202a-\u202e\U000e0000-\U000e007f]",
}
CODE = (".py", ".sh", ".js", ".mjs", ".ts", ".rb", ".ps1")
 
def frontmatter(text):
    m = re.match(r"^---\n(.*?)\n---\n?", text, re.S)
    if not m:
        return None, text
    fields, key = {}, None
    for line in m.group(1).splitlines():
        k = re.match(r"^([A-Za-z_-]+):\s*(.*)$", line)
        if k:
            key = k.group(1)
            fields[key] = k.group(2).strip().strip("\"'")
        elif key and line.startswith((" ", "\t")):
            fields[key] += " " + line.strip()
    return fields, text[m.end():]
 
def audit(root):
    rows = []
    for folder, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in (".git", "node_modules")]
        if "SKILL.md" not in files:
            continue
        text = open(os.path.join(folder, "SKILL.md"), encoding="utf-8", errors="replace").read()
        fields, body = frontmatter(text)
        everything, code_files = text, 0
        for sub, _, names in os.walk(folder):
            for n in names:
                if n.endswith(CODE):
                    code_files += 1
                if n.endswith(CODE + (".md",)) and n != "SKILL.md":
                    try:
                        everything += open(os.path.join(sub, n), encoding="utf-8", errors="replace").read()
                    except OSError:
                        pass
        flags = [name for name, pat in RISKY.items() if re.search(pat, everything)]
        if fields is None:
            flags.append("no-frontmatter")
            fields = {}
        if fields.get("allowed-tools"):
            flags.append("allowed-tools")
        if "hooks" in fields:
            flags.append("hooks")
        if re.search(r"!`[^`]+`|```!", body):
            flags.append("shell-injection-block")
        desc = (fields.get("description", "") + " " + fields.get("when_to_use", "")).strip()
        rows.append((os.path.relpath(folder, root), len(desc), len(body), code_files, flags))
    return rows
 
if __name__ == "__main__":
    rows = audit(sys.argv[1])
    listing = sum(d for _, d, _, _, _ in rows)
    print(f"{len(rows)} skills, {listing:,} description chars (~{listing // 4:,} tokens if all are listed)")
    print(f"{sum(1 for r in rows if r[3])} skills ship code files, {sum(r[3] for r in rows)} code files in total")
    for path, desc, body, code, flags in sorted(rows, key=lambda r: (-len(r[4]), r[0])):
        if flags or "-v" in sys.argv:
            print(f"  {path}: desc={desc} body={body} code={code} flags={','.join(flags) or '-'}")

把仓库克隆到项目之外的某个位置，然后让脚本指向它。

git clone --depth 1 https://github.com/obra/superpowers /tmp/superpowers
python3 audit_skills.py /tmp/superpowers

11 月 15 日 Superpowers 的输出如下：

15 skills, 2,317 description chars (~579 tokens if all are listed)
3 skills ship code files, 6 code files in total
  skills/brainstorming: desc=213 body=14933 code=3 flags=rm-rf
  skills/subagent-driven-development: desc=85 body=19484 code=0 flags=rm-rf
  skills/systematic-debugging: desc=91 body=9366 code=2 flags=reads-secrets

怎么看这些标记

一个标记的意思是「打开这个文件看看」，而不是「这个 Skill 有恶意」。这十个仓库里，凡是人工核对过的标记都是无害的。Superpowers 里命中的 rm-rf，是一个清理自身临时目录的脚本里的 rm -rf "$SESSION_DIR"。ffmpeg-skill 里命中的 hidden-unicode，是一条关于印地语连字的说明中的零宽连接符。只要提到 .env，reads-secrets 就会触发，哪怕那句话是在劝你不要提交它。

在 Claude Code 里，最后三项最要紧。allowed-tools 会在调用该 Skill 的那一轮里不经询问就放行工具。hooks 条目会在会话剩余时间里一直运行。!`command` 块在 Skill 加载时就执行。

另外两项检查

Claude Code 可以替你校验 frontmatter。在一个装了 91 个 Skill 的文件夹上，这条命令没有报任何问题；而对一个没有打包成插件的仓库，它会报 No manifest found 并失败，这说明该仓库只能靠复制安装。

claude plugin validate .claude/skills

想扫得更深，可以用 NVIDIA 的 SkillSpector (opens in a new tab)，这是一个专用扫描器，有 71 种模式和 0-100 的风险评分。下面是它 README 给出的快速用法；本文没有运行它。

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector scan ./my-skill/ --no-llm

第 2 步：只装你需要的

复制单个文件夹是环节最少的安装方式，也是本文实测的方式。

git clone --depth 1 https://github.com/janestreet/agent_skills /tmp/agent_skills
mkdir -p .claude/skills
cp -R /tmp/agent_skills/socratic-tutor .claude/skills/

目标路径决定 Skill 在哪里加载。

凡是还在试用的 Skill，优先放项目文件夹。这样它不会出现在你的其他会话里，删掉文件夹就卸载干净了。

另外两种方式来自各项目的 README，本文没有运行。

• 插件一次装下整个包，更新通过 /plugin 进行。例如先 /plugin marketplace add anthropics/skills，再 /plugin install document-skills@anthropic-agent-skills。Superpowers 则是 /plugin install superpowers@claude-plugins-official。
• Vercel Labs 的 skills CLI 会一次性为多种 Agent 把文件复制进项目：npx skills add addyosmani/agent-skills --skill test-driven-development -a claude-code。加上 --list 可以先浏览。

Claude Code 文档里有一条注意事项：skillOverrides 对插件里的 Skill 不生效。如果某个插件包太大，你只能禁用整个插件，而不能禁用其中的单个 Skill。

第 3 步：确认新 Skill 真的被列出来了

「装了却从不触发」有一种原因不会产生任何报错，这一步就是用来查它的。

Claude Code 会把每个 Skill 的名称和描述组成一份列表交给模型。这份列表有预算，默认是上下文窗口的 1%。超出预算时，Claude Code 保留所有名称，但会丢掉描述，从你用得最少的 Skill 开始丢。而刚装上的 Skill 使用次数是零。Claude Code 文档在「Skill descriptions are cut short」（Skill 描述被截短） (opens in a new tab)一节里说明了这个机制；下面的数字是它在实际机器上的样子。

下面是一台已有 84 个个人 Skill 和 14 个插件 Skill 的机器上的实际情况。复制进一个新 Skill 之后，调试日志里写着：

[WARN] Skill listing over budget: 112 skills, 37491 chars > 30000 budget — descriptions will be truncated.

而 /skill-doctor 显示新 Skill 只列出了名称：

单看 < 20 这个开销还不能下结论，因为描述只有一行的 Skill 开销本来也低于 20。要把它和描述长度对照着看。下面的统计只计入描述足够长、能够判断的 Skill。

装得越多，其他 Skill 的情况也越糟。装了 91 个项目 Skill 时，有 76 个被列出，其中 70 个丢掉了 80 个字符以上的描述。装到 289 个时，丢掉描述的个人 Skill 从 6 个涨到 39 个：新来的 Skill 把原本工作正常的 Skill 的描述挤了出去。

运行检查

/skill-doctor 为每个 Skill 打印一行，并给出它的列表开销。它需要 Claude Code 2.1.252 或更高版本，在 -p 模式下也能用。

claude -p "/skill-doctor"

想看到预算警告本身，就写一份调试日志再搜索。

claude --debug-file /tmp/cc-debug.log -p "hello"
grep "Skill listing over budget" /tmp/cc-debug.log

修复方法

先关掉你不用的。这段配置写在项目的 .claude/settings.json 里，或者写在 ~/.claude/settings.json 里对所有项目生效。

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

"name-only" 让 Skill 仍然可以用 /name 调用，同时把它的描述从列表里去掉。"off" 则把它完全隐藏。在交互式会话里，/skills 写入的是同一项设置：在某一行上按 Space 切换它的状态，再按 Esc 保存。

如果你确实每个都在用，那就调高预算。代价是每一轮都多占一些上下文。

{
  "skillListingBudgetFraction": 0.02
}

Codex 有同样的机制，只是数字不同。它的文档说，初始 Skill 列表最多占上下文窗口的 2%，窗口大小未知时为 8,000 个字符；超出时先缩短描述，还可能把部分 Skill 从列表中省略并给出警告。skills.max_context_tokens 可以修改预算，在 ~/.codex/config.toml 里加一条 enabled = false 的 [[skills.config]] 可以禁用单个 Skill。

第 4 步：让 Skill 在无人值守时运行

11 月 13 日发布的 Claude Code 2.1.325 改了一个会影响定时任务的行为。定时任务和 /loop 现在运行声明了 allowed-tools 或 hooks 的 Skill 之前会先询问。想让这样的 Skill 不经提示直接运行，就按名称放行它。

{
  "permissions": {
    "allow": ["Skill(release-notes)"]
  }
}

反过来也可以。Skill(deploy *) 这样的 deny 规则会阻止模型调用某个 Skill，不带参数地 deny Skill 则会把所有 Skill 都关掉。这两点都来自 Claude Code 文档。其余值得提交到仓库里的权限设置，见 Claude Code 权限加固。

第 5 步：移除 Skill

• 复制安装的 Skill：删除 .claude/skills/ 或 .agents/skills/ 下对应的文件夹。
• 插件里的 Skill：运行 /plugin uninstall <plugin>@<marketplace>，或者在 /plugin 里禁用它。
• 保留但不让它自动触发：在 skillOverrides 里把它设为 "name-only" 或 "off"；如果文件归你维护，也可以在它的 frontmatter 里加上 disable-model-invocation: true。

实测 vs 文档

30,000 字符的预算是一台机器报告的数值。你的预算取决于模型的上下文窗口，所以在参考百分比那一列之前，先看看你自己的调试日志。

常见问题

Claude Code 应该先装哪些 Agent Skill？

从小的开始。obra/superpowers 用 15 个 Skill 提供一整套计划、测试、调试和评审流程。addyosmani/agent-skills 再补充 25 份工程检查清单。处理表格、PDF 和幻灯片，就安装 anthropics/skills 里的 document-skills 插件。大目录只装其中的单个 Skill，不要整个装上。

为什么新装的 Claude Code Skill 不触发？

在 Skill 很多的机器上，多半是列表超出了预算，新 Skill 只列出了名称。运行 /skill-doctor。一个描述很长的 Skill 上下文开销却小于 20，就说明描述被丢掉了。用 skillOverrides 关掉不用的 Skill，或者调高 skillListingBudgetFraction。

安装之前怎么检查一个 Skill 是否安全？

把它克隆到项目之外，然后读一遍。留意自带的脚本、allowed-tools、hooks 和 !`command` 块。上文的审计脚本会为每个 SKILL.md 列出这些内容，并且不运行任何东西。

Claude Code 装多少个 Skill 算太多？

取决于描述长度，而不是数量。anthropics/skills 的 20 个 Skill 在 30,000 字符的预算里用掉约 9,500 个字符。google/skills 全装需要约 107,600 个。

/skill-doctor 是做什么的？

它会打印每个已加载的 Skill，包括来源、列表开销、7 天 token 用量和调用次数，并标出从未用过的 Skill。它需要 Claude Code 2.1.252 或更高版本。

Skill 放在哪里，Claude Code 和 Codex 才都能用？

Claude Code 用 .claude/skills/，Codex 用 .agents/skills/，放在项目里或主目录下都可以。只保留一份，另一处用符号链接。

可以不删除就禁用某个 Skill 吗？

可以：Claude Code 用设置里的 skillOverrides，Codex 用带 enabled = false 的 [[skills.config]]。插件里的 Skill 通过 /plugin 管理。

为什么 Claude Code 2.1.325 的定时任务在运行我的 Skill 之前会询问？

定时任务和 /loop 现在运行声明了 allowed-tools 或 hooks 的 Skill 之前会先询问。在 permissions.allow 里加上 Skill(name) 即可。

参考来源

• Claude Code 文档：Extend Claude with skills (opens in a new tab) 和 settings reference (opens in a new tab)
• Claude Code changelog (opens in a new tab)，2.1.325 版本
• Codex 文档：Build skills (opens in a new tab)
• Agent Skills specification (opens in a new tab)
• vercel-labs/skills (opens in a new tab) 和 NVIDIA/SkillSpector (opens in a new tab) 的 README
• Hacker News 上的 Socratic Tutor 讨论 (opens in a new tab)

相关指南

• Codex vs Claude Code Skills：设置、配置与跨工具共享技能指南
• Claude Code 权限加固：禁止写入仓库之外、权限提示直接拒绝、审计 settings.local.json
• Claude Code Mods 教程：从零写出第一个 Mod、测试与安装
• Claude Code AGENTS.md 配置指南：四种加载模式、与 CLAUDE.md 的区别、多工具共用
• OpenCode 使用指南：快速上手、实战技巧，以及何时搭配 Oh My OpenCode