平台兼容性

最后校验：2026-05-30

Agent Skills 的核心是开放的 SKILL.md 目录格式。大多数平台都能识别通用结构，但安装路径、显式触发语法和平台特有扩展并不完全相同。

通用兼容原则

跨平台 Skill 优先遵守三条原则：

1. 通用能力写进 SKILL.md：只依赖 agentskills.io 定义的 name、description、正文与标准目录。
2. 平台扩展放到平台位置：例如 Codex 的 agents/openai.yaml，不要混进通用 frontmatter。
3. 高风险行为不要依赖单个平台字段：例如禁止隐式触发时，Claude 与 Codex 要分别配置。

平台路径速查

平台	用户级	项目级	备注
Claude Code	~/.claude/skills/	<project>/.claude/skills/	首发原生支持
Claude.ai	Settings > Capabilities > Skills	—	GUI 上传，适合个人使用
Claude API	API 上传 / skill id	—	用于 API 与托管环境
OpenAI Codex CLI	~/.agents/skills/	<project>/.agents/skills/	推荐 .agents/skills/
Cursor	按平台文档配置	.cursor/skills/	按 spec 兼容
CodeBuddy	${HOME}/.codebuddy/skills/	<project>/.codebuddy/skills/	国内常用
GitHub Copilot	依平台配置	.github/skills/ 方案常见	生态仍在演进

NOTE

平台支持情况变化很快。生产落地前，应以对应平台最新文档为准。

触发方式差异

平台	隐式触发	显式触发	说明
Claude Code	根据 description	/skill <name>	部分 frontmatter 扩展只在 Claude 生效
Codex	根据 description	$<skill> 或 /skills	支持 agents/openai.yaml
Claude.ai	根据请求内容	界面选择或自然语言	更偏 GUI 使用
其它兼容平台	通常根据 description	依平台而定	优先查平台文档

显式触发适合调试：当你知道应该用某个 Skill，但隐式触发不稳定，可以先显式调用，再回头优化 description。

平台特有字段

Claude Code

Claude Code 可在 SKILL.md frontmatter 使用额外字段：

---
name: manual-only-skill
description: Use when ...
disable-model-invocation: true
---

常见字段：

字段	作用
disable-model-invocation: true	禁止模型自动触发，只允许用户手动调用
user-invocable: false	禁止用户手动调用

这些不是 agentskills.io 通用字段，其他平台可能忽略。

OpenAI Codex

Codex 使用 sidecar 文件：

my-skill/
└── agents/
    └── openai.yaml

常见用途：

• UI 展示元数据
• 禁止隐式触发
• 声明 MCP 等工具依赖

详见 Codex Skills。

禁止隐式触发的跨平台写法

如果一个 Skill 只应手动调用，不应自动触发，Claude 与 Codex 要分别配置。

# SKILL.md
---
name: dangerous-operation
description: Use when the user explicitly asks to run a high-risk maintenance workflow.
disable-model-invocation: true
---

# agents/openai.yaml
policy:
  allow_implicit_invocation: false

只设置一边，就只对一个平台生效。

兼容性 checklist

• [ ] name 与目录名一致
• [ ] name 使用 kebab-case
• [ ] description 不写执行步骤
• [ ] 文件路径使用 /
• [ ] SKILL.md 不依赖平台私有字段才能工作
• [ ] 平台私有配置放在对应位置
• [ ] 禁止隐式触发时 Claude / Codex 都配置
• [ ] MCP 工具在正文里使用全限定名
• [ ] 在目标平台实际触发过一次

下一步

• 通用字段看 SKILL.md。
• Codex 专属扩展看 Codex Skills。
• 工具和校验看 工具与校验。