skill-portability

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

skill-portability

—

Audits whether an agent skill loads and behaves correctly across the major providers — Claude Code, Cursor, OpenAI Codex CLI, and the Agents-Skills Baseline (covering Gemini CLI, OpenCode, Pi). See

scripts/providers.mjs

for the canonical list. The audit covers three layers:

Format-level — does the file/dir structure and frontmatter match what the provider expects?
Body-level — does the body reference provider-specific conventions (XML tags, headings) that other providers ignore?
Tool-surface-level — does the body name tools (e.g.,
```
AskUserQuestion
```
) that only exist in one provider?

The canonical provider list, required/forbidden frontmatter fields, and bundled doc snapshots live in

scripts/providers.mjs

and

references/providers/

. Provider docs are refreshed at authoring time via

pnpm skill-tools refresh-provider-docs

and committed — the audit never fetches at runtime, so per-provider verdicts are deterministic and offline-capable.

Claude Code extensions (其他Agent会忽略) --- argument-hint: '[<skill-path-or-name>]' user-invocable: true model-invocable: true

When to use

skill-portability

Verbatim trigger phrases:

"is this skill cross-provider safe"
"will my skill work in cursor"
"will this load in codex"
"audit skill compatibility"
"check if this skill is portable"
"which providers support this skill"
"is my skill claude-only"

审计Agent技能能否在主流提供商（Claude Code、Cursor、OpenAI Codex CLI以及Agents-Skills基准测试套件，涵盖Gemini CLI、OpenCode、Pi）中正确加载并运行。提供商的标准列表请查看

scripts/providers.mjs

。审计涵盖三个层面：

格式层面 — 文件/目录结构和前置元数据是否符合提供商的要求？
内容层面 — 技能内容是否引用了其他提供商不支持的特定约定（如XML标签、标题格式）？
工具层面 — 技能内容是否调用了仅在某一个提供商中存在的工具（例如
```
AskUserQuestion
```
）？

提供商的标准列表、必填/禁用的前置元数据字段以及捆绑的文档快照存储在

scripts/providers.mjs

和

references/providers/

中。提供商文档会在开发阶段通过

pnpm skill-tools refresh-provider-docs

命令刷新并提交——审计过程中不会在运行时获取文档，因此每个提供商的判定结果是确定性的，且支持离线使用。

When NOT to use

使用场景

Authoring a brand-new skill → use
```
skill-creator
```
Rerunning a skill's existing eval baselines → use
```
skill-eval
```
Linting a skill against this monorepo's rules → use
```
pnpm skill-tools lint
```
Comparing skill behavior across model versions → that's
```
skill-eval
```
, not this

明确的触发语句：

"这个技能跨提供商安全吗"
"我的技能能在Cursor中运行吗"
"这个技能能在Codex中加载吗"
"审计技能兼容性"
"检查这个技能是否可移植"
"哪些提供商支持这个技能"
"我的技能是不是只能在Claude中使用"

Inputs

禁用场景

$ARGUMENTS

— one of:

A path to a skill directory (

skills/code-reviewer/

skills/skill-creator/

)

A path to a single SKILL.md / .mdc / AGENTS.md file
A glob (
```
skills/*
```
) — bulk audit
A literal frontmatter+body block pasted into the prompt
Empty — discover via
```
ls skills/
```
and ask which to audit

编写全新技能 → 使用
```
skill-creator
```
重新运行技能的现有基准测试 → 使用
```
skill-eval
```
针对本单体仓库规则对技能进行代码检查 → 使用
```
pnpm skill-tools lint
```
跨模型版本比较技能行为 → 这是
```
skill-eval
```
的功能，而非本技能

Workflow

输入参数

1. Resolve the input

—

Determine what the user is auditing.

Input	Action
Directory path	Read the SKILL.md (or .mdc / AGENTS.md) inside
Single file path	Read the file directly
Glob	Expand and audit each match
Pasted content	Treat the prompt body as the skill content
Empty `$ARGUMENTS`	List `skills/*/SKILL.md` and ask the user which to audit

Parse the frontmatter (YAML between leading

---

markers) and remember the body content. Both feed into the per-provider checks.

$ARGUMENTS

— 以下任意一种：

技能目录路径（例如

skills/code-reviewer/

或

skills/skill-creator/

）

单个SKILL.md/.mdc/AGENTS.md文件的路径
通配符（例如
```
skills/*
```
）——批量审计
粘贴到提示中的前置元数据+内容块
空值 — 通过
```
ls skills/
```
自动发现并询问用户要审计哪个技能

2. Load the canonical provider list

工作流程

—

1. 解析输入

Run the bundled ESM script — no shell required, works on macOS, Linux, and Windows:

bash

node skills/skill-portability/scripts/providers.mjs --pretty

Capture the JSON. Each entry has

id

name

fileFormat

fileLocation

docUrls

localDocPath

requiredFrontmatter

optionalFrontmatter

ignoredFrontmatter

forbiddenFrontmatter

toolSurface

, and

notes

This script is the single source of truth. Don't hardcode provider details into the audit body — re-run the script each time.

确定用户要审计的对象。

输入类型	操作说明
目录路径	读取目录内的SKILL.md（或.mdc/AGENTS.md）文件
单个文件路径	直接读取该文件内容
通配符	展开通配符并审计每个匹配项
粘贴的内容块	将提示内容视为技能内容进行处理
空值 `$ARGUMENTS`	列出 `skills/*/SKILL.md` 并询问用户要审计哪个技能

解析前置元数据（开头

---

标记之间的YAML内容）并保留技能正文内容，两者都会用于后续的提供商检查。

3. Fan out: one agent per provider, in parallel

2. 加载标准提供商列表

Dispatch one

Agent

call per provider returned by step 2 (concurrent — one tool message with all tool uses). Don't hardcode the count —

providers.mjs

is the source of truth and may grow. Each agent gets:

The provider entry from step 2 (id, format requirements, toolSurface, notes)
The bundled provider doc snapshot read from
```
localDocPath
```
(e.g.
```
references/providers/cursor.md
```
). Read the file with the
```
Read
```
tool before dispatching the subagent and pass its contents inline in the subagent prompt — do NOT instruct the subagent to fetch.
The skill content from step 1 (frontmatter + body)
These instructions to the subagent:
Use the provider doc snapshot included in this prompt — it was bundled with the skill at authoring time and is the authoritative reference for this audit. Do NOT WebFetch any URL; if the snapshot is missing details, surface that as a NOTES finding rather than fetching.

Evaluate the skill against three layers:
1. Format: does it match
```
fileFormat
```
  ? Are all
```
requiredFrontmatter
```
  fields present? Are any
```
forbiddenFrontmatter
```
  fields present?
2. Body: does the body lean on conventions this provider doesn't parse (e.g., XML tags Cursor strips, headings the baseline ignores)?
3. Tool surface: does the body name tools not in this provider's
```
toolSurface
```
  ? List each unmatched tool name.
Return a structured verdict:
```
VERDICT: compatible | partial | incompatible
FORMAT: <one-line summary>
BODY: <one-line summary>
TOOLS: <comma-separated unmatched tool names, or "none">
NOTES: <2–3 specific findings with file/line references where possible>
```

Use

subagent_type: "general-purpose"

. Run all dispatches in one message so they execute concurrently.

运行捆绑的ESM脚本——无需shell，支持macOS、Linux和Windows：

bash

node skills/skill-portability/scripts/providers.mjs --pretty

捕获JSON结果。每个条目包含

id

、

name

、

fileFormat

、

fileLocation

、

docUrls

、

localDocPath

、

requiredFrontmatter

、

optionalFrontmatter

、

ignoredFrontmatter

、

forbiddenFrontmatter

、

toolSurface

和

notes

字段。

该脚本是唯一的事实来源，请勿将提供商细节硬编码到审计逻辑中——每次都要重新运行该脚本。

4. Aggregate the verdicts into a matrix

3. 并行分发：每个提供商对应一个Agent

Build a markdown table with one row per provider and one column per layer:

| Provider                | Verdict      | Format              | Body          | Tools          |
| ----------------------- | ------------ | ------------------- | ------------- | -------------- |
| Claude Code             | compatible   | SKILL.md ✓          | clean         | -              |
| Cursor                  | partial      | needs .mdc          | XML stripped  | -              |
| OpenAI Codex CLI        | partial      | rename to AGENTS.md | clean         | Bash → shell   |
| Agents-Skills Baseline  | compatible   | SKILL.md ✓          | clean         | tool names vary |

Add a

NOTES

paragraph below summarizing the most actionable change to make the skill more portable.

针对步骤2返回的每个提供商，分发一次

Agent

调用（并发执行——通过一条工具消息包含所有工具调用）。请勿硬编码提供商数量——

providers.mjs

是事实来源，可能会新增提供商。每个Agent会收到：

步骤2中的提供商条目（id、格式要求、toolSurface、notes）
从
localDocPath
读取的捆绑提供商文档快照（例如
```
references/providers/cursor.md
```
）。在分发子Agent前使用
```
Read
```
工具读取文件内容，并将内容内联到子Agent的提示中——请勿指示子Agent去获取文档。
步骤1中的技能内容（前置元数据+正文）
给子Agent的以下指令：
使用本提示中包含的提供商文档快照——该快照在技能开发阶段已捆绑，是本次审计的权威参考。请勿使用WebFetch获取任何URL；如果快照缺少细节，请将其作为NOTES结果列出，而非去获取文档。

从三个层面评估技能：
1. 格式：是否符合
```
fileFormat
```
  要求？所有
```
requiredFrontmatter
```
  字段是否存在？是否包含任何
```
forbiddenFrontmatter
```
  字段？
2. 内容：技能内容是否依赖该提供商不解析的约定（例如Cursor会剥离的XML标签、基准测试套件会忽略的标题）？
3. 工具层面：技能内容是否调用了不在该提供商
```
toolSurface
```
  中的工具？列出每个不匹配的工具名称。
返回结构化的判定结果：
```
VERDICT: compatible | partial | incompatible
FORMAT: <单行摘要>
BODY: <单行摘要>
TOOLS: <逗号分隔的不匹配工具名称，或"none">
NOTES: <2-3条具体结果，尽可能包含文件/行号引用>
```

使用

subagent_type: "general-purpose"

。所有分发操作在一条消息中完成，以便并发执行。

5. Write COMPAT.md and print the matrix inline

4. 将判定结果汇总为矩阵

Two outputs:

Inline: print the matrix + notes in chat so the user sees it immediately.
Persisted: write
```
<skill-dir>/COMPAT.md
```
(or
```
./COMPAT.md
```
if no skill dir), containing: the matrix, the per-provider verdict bodies, the timestamp, and the
```
providers.mjs
```
```
docUrls
```
actually fetched. The user can diff this over time to spot regressions when providers move docs.

For bulk audits (glob input), produce one combined matrix where rows are skills, columns are providers, and write

COMPAT.md

at the repo root.

构建一个Markdown表格，每行对应一个提供商，每列对应一个评估层面：

| 提供商                | 判定结果      | 格式检查              | 内容检查          | 工具检查          |
| ----------------------- | ------------ | ------------------- | ------------- | -------------- |
| Claude Code             | 兼容   | SKILL.md ✓          | 合规         | -              |
| Cursor                  | 部分兼容      | 需要转换为.mdc格式          | XML标签会被剥离  | -              |
| OpenAI Codex CLI        | 部分兼容      | 需要重命名为AGENTS.md | 合规         | Bash → shell   |
| Agents-Skills Baseline  | 兼容   | SKILL.md ✓          | 合规         | 工具名称因消费者而异 |

在表格下方添加

NOTES

段落，总结使技能更具可移植性的最可行修改建议。

6. Handle missing or stale snapshots

5. 写入COMPAT.md并在聊天中打印矩阵

If any provider's

localDocPath

doesn't exist or its snapshot is empty / truncated to a placeholder, surface this in the inline output:

⚠ Provider snapshot missing or sparse: `cursor` — references/providers/cursor.md
  is 503 bytes (likely SPA-rendered upstream). Verdict relies on the
  `notes` field. Run `pnpm skill-tools refresh-provider-docs` to refresh.

Don't silently fall back to WebFetch — that's exactly the runtime fetch behavior the bundled-snapshot design avoids. If a snapshot is genuinely missing, treat it as

unknown

in the verdict rather than guessing.

To refresh snapshots from upstream (dev-time, not runtime):

bash

pnpm skill-tools refresh-provider-docs

To verify URLs still resolve (HEAD requests, no body fetch):

bash

node skills/skill-portability/scripts/providers.mjs --check

输出分为两部分：

即时输出：在聊天中打印矩阵+备注，让用户立即看到结果。
持久化输出：将内容写入
```
<skill-dir>/COMPAT.md
```
（如果没有技能目录则写入
```
./COMPAT.md
```
），包含：矩阵、每个提供商的完整判定结果、时间戳以及
```
providers.mjs
```
中实际获取的
```
docUrls
```
。用户可以通过对比不同版本的COMPAT.md来发现提供商文档更新导致的兼容性退化。

对于批量审计（通配符输入），生成一个组合矩阵，行对应技能，列对应提供商，并将COMPAT.md写入仓库根目录。

Examples

6. 处理缺失或过期的快照

<example> <input>"is my code-reviewer skill cross-provider safe? it's at skills/code-reviewer/"</input> <output> 1. Resolve: read `skills/code-reviewer/SKILL.md` → frontmatter has `name`, `description`, `argument-hint`, `user-invocable`, `model-invocable`. Body uses `<example>` blocks and references `AskUserQuestion`, `gh pr diff`, and a sibling `scripts/detect-clis.mjs`. 2. Load providers: `node skills/skill-portability/scripts/providers.mjs --pretty` → entries returned (currently 4). 3. Fan out one parallel `Agent` call per provider — Claude Code, Cursor, Codex CLI, Agents-Skills Baseline. 4. Aggregate verdicts:

Provider	Verdict	Notes
Claude Code	compatible	native format
Cursor	partial	needs `.cursor/rules/code-reviewer.mdc` ; references/ won't load
OpenAI Codex CLI	partial	rename to AGENTS.md; `AskUserQuestion` not in tool surface
Agents-Skills Baseline	compatible	loads from `.agents/skills/` ; tool names vary per consumer

Write
```
skills/code-reviewer/COMPAT.md
```
with full per-provider bodies. </output> </example>

<example> <input>Pasted: a `.mdc` file with `globs:` and `alwaysApply:` in frontmatter — "will this load in claude code?"</input> <output> 1. Resolve: parse pasted content. Frontmatter: `description`, `globs`, `alwaysApply`. No `name` field. 2. Load providers list. 3. Fan out 4 parallel agents. 4. Verdicts:

Claude Code: incompatible — missing required
```
name
```
field;
```
skills
```
CLI rejects without it.
```
globs
```
/
```
alwaysApply
```
are silently ignored.
Cursor: compatible — this is native
```
.mdc
```
format.
Codex CLI: partial — Codex reads AGENTS.md as plain markdown; frontmatter is silently ignored, content would still apply.
Continue.dev: partial — move to
```
.continue/rules/<name>.md
```
;
```
globs
```
is supported,
```
alwaysApply
```
is not.

Recommend: add
```
name: <kebab-case>
```
to make portable; consider dropping
```
alwaysApply
```
since only Cursor honors it. </output> </example>

<example> <good> Ran `node scripts/providers.mjs --pretty` once at step 2. For each provider, Read its `localDocPath` snapshot and inlined the contents into the subagent prompt. Subagents evaluated against bundled docs — no runtime WebFetch. </good> <bad> Instructed subagents to WebFetch the provider docUrls at audit time. Result: slow audits, stale-doc false negatives, runtime dependency on every provider's docs site staying up. </bad>

The bad version reintroduces the runtime URL fetch the snapshot pattern exists to avoid. Snapshots are committed; refresh on cadence with

pnpm skill-tools refresh-provider-docs

. </example>

如果任何提供商的

localDocPath

不存在，或快照为空/被截断为占位符，请在即时输出中提示：

⚠ 提供商快照缺失或不完整: `cursor` — references/providers/cursor.md
  大小为503字节（上游可能是SPA渲染）。判定结果基于`notes`字段。请运行`pnpm skill-tools refresh-provider-docs`来刷新快照。

请勿静默回退到WebFetch——这正是捆绑快照设计要避免的运行时获取行为。如果快照确实缺失，请在判定结果中标记为

unknown

，而非猜测。

从上游刷新快照（开发阶段，非运行时）：

bash

pnpm skill-tools refresh-provider-docs

验证URL是否仍可访问（HEAD请求，不获取内容）：

bash

node skills/skill-portability/scripts/providers.mjs --check

References

示例

```
scripts/providers.mjs
```
— canonical provider list, format requirements,
```
localDocPath
```
for each provider's bundled snapshot. Run
```
--check
```
to verify upstream URLs still resolve.
```
references/providers/
```
— per-provider doc snapshots (auto-generated; refresh via
```
pnpm skill-tools refresh-provider-docs
```
).
```
references/provider-formats.md
```
— per-provider deep dive: frontmatter shape, file location conventions, tool surface, common porting gotchas.
```
references/audit-prompt.md
```
— the verbatim prompt template handed to each subagent in step 3.

<example> <input>"我的code-reviewer技能跨提供商安全吗？它在skills/code-reviewer/目录下"</input> <output> 1. 解析输入: 读取`skills/code-reviewer/SKILL.md` → 前置元数据包含`name`、 `description`、`argument-hint`、`user-invocable`、`model-invocable`。正文使用`<example>`块并引用`AskUserQuestion`、`gh pr diff` 以及同级的`scripts/detect-clis.mjs`。 2. 加载提供商列表: `node skills/skill-portability/scripts/providers.mjs --pretty` → 返回4个条目。 3. 并行分发4个`Agent`调用——分别对应Claude Code、Cursor、Codex CLI、Agents-Skills Baseline。 4. 汇总判定结果:

提供商	判定结果	备注
Claude Code	兼容	原生格式支持
Cursor	部分兼容	需要转换为 `.cursor/rules/code-reviewer.mdc` 格式；references/目录无法加载
OpenAI Codex CLI	部分兼容	需要重命名为AGENTS.md； `AskUserQuestion` 不在工具列表中
Agents-Skills Baseline	兼容	可从 `.agents/skills/` 加载；工具名称因消费者而异

将完整的提供商判定结果写入
```
skills/code-reviewer/COMPAT.md
```
。 </output> </example>

<example> <input>粘贴内容: 一个前置元数据包含`globs:`和`alwaysApply:`的.mdc文件 — "这个技能能在Claude Code中加载吗？"</input> <output> 1. 解析输入: 解析粘贴的内容。前置元数据包含`description`、`globs`、 `alwaysApply`，缺少`name`字段。 2. 加载提供商列表。 3. 并行分发4个Agent调用。 4. 判定结果:

Claude Code: 不兼容 — 缺少必填的
```
name
```
字段；
```
skills
```
CLI会拒绝加载。
```
globs
```
/
```
alwaysApply
```
会被静默忽略。
Cursor: 兼容 — 这是原生.mdc格式。
Codex CLI: 部分兼容 — Codex将AGENTS.md视为纯markdown；前置元数据会被静默忽略，但内容仍可正常运行。
Continue.dev: 部分兼容 — 需要移动到
```
.continue/rules/<name>.md
```
；支持
```
globs
```
，但不支持
```
alwaysApply
```
。

建议: 添加
```
name: <kebab-case>
```
字段以提升可移植性；考虑移除
```
alwaysApply
```
，因为只有Cursor支持该字段。 </output> </example>

<example> <good> 在步骤2中仅运行一次`node scripts/providers.mjs --pretty`。针对每个提供商，读取其`localDocPath`快照并将内容内联到子Agent的提示中。子Agent基于捆绑文档进行评估——无运行时WebFetch操作。 </good> <bad> 指示子Agent在审计时通过WebFetch获取提供商的docUrls。结果: 审计速度慢、因文档过期导致误判、运行时依赖所有提供商文档站点保持可用。 </bad>

错误版本重新引入了快照模式本应避免的运行时URL获取行为。快照已提交到仓库；请定期使用

pnpm skill-tools refresh-provider-docs

命令刷新。 </example>

—

参考资料

—

```
scripts/providers.mjs
```
— 标准提供商列表、格式要求、每个提供商捆绑快照的
```
localDocPath
```
。运行
```
--check
```
参数可验证上游URL是否仍可访问。
```
references/providers/
```
— 各提供商的文档快照（自动生成；通过
```
pnpm skill-tools refresh-provider-docs
```
命令刷新）。
```
references/provider-formats.md
```
— 各提供商深度解析：前置元数据格式、文件位置约定、工具列表、常见移植陷阱。
```
references/audit-prompt.md
```
— 步骤3中传递给每个子Agent的完整提示模板。