指南

各 AI 编程 agent 中的 Agent Skills(SKILL.md):Claude Code、Codex、Cline、Amp 和 OpenHands(2026)

每个 AI 编程 agent 在哪里查找 SKILL.md skill?一个 skill 文件夹能否在所有 agent 中通用?

这些 agent 都会读取一个包含 SKILL.md 文件的文件夹,该文件的 YAML frontmatter 包含 name 和 description。Claude Code 使用 .claude/skills/ 和 ~/.claude/skills/。Codex、Amp 和 OpenHands 在仓库中使用 .agents/skills/,个人使用 ~/.agents/skills/。Cline 使用 .cline/skills/ 和 ~/.cline/skills/,也会读取 .claude/skills/。Amp 也会读取 .claude/skills/。因此,放在 .agents/skills/ 中的 skill 覆盖 Codex、Amp 和 OpenHands,在 .claude/skills/ 中放一份副本则覆盖 Claude Code、Cline 和 Amp。

本文译自英文版指南。命令、配置键与代码均保持原样;如有出入,以英文版为准。 阅读英文原版 → · 其他语言: 日本語 · 한국어 · Español · Português (Brasil)

设置一变,第一时间知道

当这些工具的设置、参数或权限规则发生变化时,每周一封邮件通知你(英文),内容均对照官方文档核实。

快速答案:skill 文件夹位置

  • Claude Code:.claude/skills/NAME/SKILL.md(项目)和 ~/.claude/skills/NAME/SKILL.md(个人)。插件也可附带 skill,以 /plugin-name:skill-name 调用。
  • OpenAI Codex:启动 Codex 的文件夹中的 .agents/skills、直到仓库根目录的各上级文件夹、~/.agents/skills、/etc/codex/skills(管理员)以及内置的系统 skill。
  • Cline:项目中的 .cline/skills/(推荐)、.clinerules/skills/ 或 .claude/skills/,全局为 ~/.cline/skills/。
  • Amp:项目及上级文件夹中的 .agents/skills/ 和 .claude/skills/、~/.config/agents/skills/、~/.agents/skills/、~/.config/amp/skills/、~/.claude/skills/,以及 amp.skills.path 中列出的文件夹。
  • OpenHands:仓库中的 .agents/skills/NAME/SKILL.md(旧版 .openhands/skills 和 .openhands/microagents 仍可用),用户级为 ~/.agents/skills。

一个处处可用的 SKILL.md

这五个 agent 都接受同样的最简文件:包含 name 和 description 的 YAML frontmatter,后面是 Markdown 指令。name 要与文件夹名一致,因为 Cline 和 OpenHands 要求两者匹配。

.agents/skills/release-notes/SKILL.md

---
name: release-notes
description: Draft release notes from recent commits. Use when the user asks for release notes or a changelog.
---

1. Read the commits since the last tag.
2. Group changes into Features, Fixes and Other.
3. Write the notes in plain Markdown.
  • 将其放在 .agents/skills/release-notes/ 中,供 Codex、Amp 和 OpenHands 使用。
  • 将同一个文件夹放在 .claude/skills/ 中,供 Claude Code 使用。Cline 和 Amp 也会读取该文件夹。
  • 把 description 写成触发条件:说明 skill 做什么、何时使用。Claude Code、Codex、Cline 和 Amp 根据这段文字决定是否加载 skill。

如何运行 skill

  • Claude Code:输入 /skill-name,或在请求与 description 匹配时让 Claude 自动加载。名称后面的文字会填入 $ARGUMENTS。
  • Codex:运行 /skills 或输入 $ 加 skill 名称,或让 Codex 根据 description 自行选择。
  • Cline:输入 / 并选择 skill,或在请求匹配时让 Cline 自动加载。
  • Amp:模型能看到每个 skill 的 name 和 description,在调用 skill 时加载完整的 SKILL.md。用 amp skill add <source> 安装 skill。
  • OpenHands:在 frontmatter 中添加 triggers 列表,只有消息中出现其中某个关键词时才加载 skill。

阻止 agent 自行使用 skill

  • Claude Code:在 frontmatter 中设置 disable-model-invocation: true。之后只有你能运行它。
  • Codex:在 agents/openai.yaml 中设置 policy.allow_implicit_invocation: false。显式的 $skill 调用仍然有效。要完全禁用某个 skill,在 ~/.codex/config.toml 中添加一个 enabled = false 的 [[skills.config]] 条目。
  • Cline:在聊天框下方天平图标菜单的 Skills 标签页中关闭该 skill。
  • Amp:设置 amp.skills.disableClaudeCodeSkills 以跳过 Claude 兼容的文件夹。
  • OpenHands:使用 triggers 列表,让 skill 只在匹配关键词时加载。

名称冲突时哪个副本生效

  • Claude Code:企业级优先于个人级,个人级优先于项目级。skill 优先于同名的 .claude/commands/ 文件。
  • Codex:同名 skill 不会合并,两者都会出现在选择器中。
  • Cline:全局 skill 优先于同名的项目 skill。
  • Amp:按搜索顺序找到的第一个 skill 生效。

常见陷阱

  • Codex 将初始 skill 列表限制在上下文窗口的 2%(大小未知时为 8,000 个字符),skill 很多时会优先缩短 description。
  • Cline 建议 SKILL.md 保持在 5k token 以内;每个 skill 的元数据在启动时约占 100 个 token。
  • 在其他地方运行 amp skills list 时,Amp 不会在正在运行的 thread 中重新加载 skill。请让 Amp 重新加载你的 skill。
  • Claude Code 已将自定义命令合并到 skill 中,所以 .claude/commands/*.md 文件仍会创建 /name 命令。

各 agent 的完整 skill 指南

来源

以下为本指南核对过的官方文档(英文)。 英文版核对日期: 2026-10-18

更多中文指南