cross-agent-skill-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cross-Agent Skill Sync

跨Agent Skill同步

Use this skill to manage existing skills across multiple AI agents. It does not create, edit, download, or upgrade skills. It discovers configured source skills, explains current status clearly, plans symlink changes, and applies them only after explicit confirmation.

使用此Skill可管理多个AI Agent中的现有Skill。它不会创建、编辑、下载或升级Skill，仅会发现已配置的源Skill，清晰说明当前状态，规划符号链接变更，且仅在获得明确确认后才会应用变更。

Hard boundaries

严格边界

Do not install new skills.
Do not call
```
npx skills add
```
,
```
skills add
```
,
```
git clone
```
, or any other installation workflow.
Do not edit source skill contents.
Do not use
```
rm -rf
```
.
Only remove symlinks with
```
unlink
```
, and only when the target is actually a symlink.
If a target path is a real directory or file, refuse to remove it and report the reason.
Never execute changes before the user has confirmed the dry-run plan.

请勿安装新Skill。
请勿调用
```
npx skills add
```
、
```
skills add
```
、
```
git clone
```
或任何其他安装流程。
请勿编辑源Skill内容。
请勿使用
```
rm -rf
```
。
仅可使用
```
unlink
```
移除符号链接，且仅当目标确实是符号链接时执行。
若目标路径是真实目录或文件，拒绝移除并报告原因。
在用户确认试运行计划前，绝不要执行任何变更。

Core rule

核心规则

This skill is a strict guided workflow, not an autonomous operator.

Every time the skill triggers:

Explain how the workflow will proceed.
Determine the action.
Collect required selections in a fixed order.
Stop at the first missing selection and ask only for that item.
Do not continue until the user has answered that specific step.
After all required inputs are complete, show a dry-run plan or a structured status summary.
Apply changes only after explicit confirmation.
End with a structured result summary.

If the model can infer some fields from the user's original request, keep them. If a field is not explicit, do not guess. Ask.

This skill has two equally important entry scenarios:

direct operation: the user already knows what they want to sync, remove, or repair
status-first exploration: the user does not yet know the current skill state and wants to inspect skill differences before deciding what to do

For

inventory

status

, and

sync

, the main gating order is action, scope, source, then the rest. For

remove

, source is not required because removal only affects target-side links. The subject must stay centered on

skill

skills

agent skill

agent skills

, or equivalent wording. Do not trigger this skill for generic agent-state or model-comparison questions that are not about skills.

此Skill是严格的引导式工作流，而非自主操作工具。

每次触发Skill时：

说明工作流的执行步骤。
确定操作类型。
按固定顺序收集所需选项。
遇到第一个缺失的选项时停止，仅询问该选项。
直到用户回答该特定步骤后才可继续。
收集完所有必要输入后，展示试运行计划或结构化状态摘要。
仅在获得明确确认后才应用变更。
以结构化结果摘要结束。

若模型可从用户原始请求中推断出某些字段，可保留这些字段；若字段不明确，请勿猜测，直接询问。

此Skill有两个同等重要的触发场景：

直接操作：用户已明确要进行同步、移除或修复操作
先查状态：用户不了解当前Skill状态，想要先检查Skill差异再决定操作

对于

inventory

、

status

和

sync

操作，核心流程顺序为：操作类型 → 范围 → 源 → 其他选项。对于

remove

操作，无需选择源，因为移除仅影响目标端的链接。主题必须围绕

skill

、

skills

、

agent skill

、

agent skills

或等效表述。请勿因与Skill无关的通用Agent状态或模型对比问题触发此Skill。

What to say first

初始说明

At the start of the interaction, explain the workflow in plain language before doing anything else. Use this shape:

text

I will handle this request in a fixed order:
1. Confirm the scope
2. If this is sync or status work, confirm the source
3. Confirm the skill selection
4. Confirm the target agents
5. Show you a dry-run plan or a status summary
6. Only execute after you confirm

If the user already provided some of these items, say that you will keep the provided values and ask only for the missing ones. If the request sounds like "show me the current skill state first" or "I am not sure what to change yet", first check that the topic is clearly about skills or agent skills. If it is, say that you will first clarify scope and source, then show a skill-status summary before proposing any change.

在交互开始时，先以通俗易懂的语言说明工作流，再执行其他操作，格式如下：

text

我将按以下固定顺序处理您的请求：
1. 确认范围
2. 若为同步或状态查询操作，确认源
3. 确认Skill选择
4. 确认目标Agent
5. 为您展示试运行计划或状态摘要
6. 仅在您确认后执行操作

若用户已提供部分选项，说明将保留这些值，仅询问缺失的选项。若用户请求类似"先展示当前Skill状态"或"我还不确定要做什么变更"，首先确认主题是否明确围绕Skill或Agent Skill。若是，说明将先明确范围和源，再展示Skill状态摘要，之后再提出变更建议。

Supported actions

支持的操作类型

Classify the request into one of these actions:

```
inventory
```
: list available skills from selected sources
```
status
```
: show missing skills, linked state, external-source coverage, or sync coverage
```
sync
```
: create or repair symlinks
```
remove
```
: unlink selected symlink targets

If the action is unclear, stop and ask which action the user wants. Do not inspect sources or targets until the action is clear.

When the user says things like:

"I am not sure about the current skill state"
"Show me the skill differences first"
"I have not checked these agent skills in a while"
"Analyze the agent skill state before I decide what to sync"

Prefer

status

inventory

rather than jumping to

sync

Do not trigger this skill for prompts like:

"I am not sure about these agents"
"Compare these models"
"Which agent performs better"

unless the prompt clearly brings the topic back to skills or agent skills.

将用户请求归类为以下操作之一：

```
inventory
```
：列出所选源中的可用Skill
```
status
```
：展示缺失的Skill、链接状态、外部源覆盖情况或同步覆盖情况
```
sync
```
：创建或修复符号链接
```
remove
```
：移除所选符号链接目标

若操作类型不明确，停止并询问用户需要执行哪种操作。在明确操作类型前，请勿检查源或目标。

当用户表述如下内容时：

"我不确定当前Skill状态"
"先给我看Skill差异"
"我有段时间没检查这些Agent的Skill了"
"先分析Agent Skill状态，我再决定要同步什么"

优先选择

status

或

inventory

操作，而非直接跳转到

sync

。

请勿因以下提示触发此Skill：

"我不确定这些Agent的情况"
"对比这些模型"
"哪个Agent性能更好"

除非提示明确将主题拉回Skill或Agent Skill。

Config model

配置模型

The script is configuration-driven.

User-level config default path:

~/.config/cross-agent-skill-sync/config.conf

Project-level config default path:
```
./.cross-agent-skill-sync.conf
```
Optional explicit override:
```
SKILL_SYNC_CONFIG=/path/to/config.conf
```

The config file is shell syntax, not JSON. Read

references/config.example.conf

when the user wants to add a new source or a new agent mapping.

Configuration shape:

```
SOURCE_<name>=/absolute/path
```
```
AGENT_<name>_USER=/absolute/path
```

AGENT_<name>_PROJECT=.relative/path/from/project/root

AGENT_<name>_EXTERNAL_SOURCES=source_a,source_b

AGENT_<name>_EXTERNAL_SOURCES

means that the agent automatically loads those configured external sources in addition to its own skill directory. This is useful for tools such as Gemini that already read

~/.agents/skills

Default sources:

```
cc-switch
```
```
agents
```

Default agents:

```
claude-code
```
```
codex
```
```
gemini
```
```
opencode
```
```
openclaw
```
```
cursor
```
```
copilot
```

脚本由配置驱动。

用户级配置默认路径：

~/.config/cross-agent-skill-sync/config.conf

项目级配置默认路径：
```
./.cross-agent-skill-sync.conf
```
可选显式覆盖：
```
SKILL_SYNC_CONFIG=/path/to/config.conf
```

配置文件采用Shell语法，而非JSON。当用户想要添加新源或新Agent映射时，可参考

references/config.example.conf

。

配置格式：

```
SOURCE_<name>=/absolute/path
```
```
AGENT_<name>_USER=/absolute/path
```

AGENT_<name>_PROJECT=.relative/path/from/project/root

AGENT_<name>_EXTERNAL_SOURCES=source_a,source_b

AGENT_<name>_EXTERNAL_SOURCES

表示该Agent除自身Skill目录外，还会自动加载这些已配置的外部源。这对Gemini等已读取

~/.agents/skills

的工具非常有用。

默认源：

```
cc-switch
```
```
agents
```

默认Agent：

```
claude-code
```
```
codex
```
```
gemini
```
```
opencode
```
```
openclaw
```
```
cursor
```
```
copilot
```

Missing config behavior

缺失配置的处理方式

Before collecting the rest of the workflow inputs, check whether any explicit config file exists:

~/.config/cross-agent-skill-sync/config.conf

```
./.cross-agent-skill-sync.conf
```
the file pointed to by
```
SKILL_SYNC_CONFIG
```
, if present

If none of them exists, stop and ask the user whether to create a default config first.

Allowed responses:

create a user-level default config
create a project-level default config
continue without creating one and use built-in defaults

Never create config files without explicit approval.

在收集工作流的其他输入前，检查是否存在任何显式配置文件：

~/.config/cross-agent-skill-sync/config.conf

```
./.cross-agent-skill-sync.conf
```
若存在
```
SKILL_SYNC_CONFIG
```
环境变量，则检查其指向的文件

若以上文件均不存在，停止操作并询问用户是否要先创建默认配置。

允许的回复：

创建用户级默认配置
创建项目级默认配置
不创建配置，使用内置默认值继续

未经明确许可，绝不要创建配置文件。

Mandatory workflow

强制工作流

Follow this order every time. Do not skip ahead.

每次均需遵循以下顺序，不得跳过步骤。

Step 0: Confirm action

步骤0：确认操作类型

If the request does not clearly say whether the user wants

inventory

status

sync

, or

remove

, ask only for the action.

若请求未明确说明用户需要

inventory

、

status

、

sync

还是

remove

操作，仅询问操作类型。

Step 1: Confirm scope

步骤1：确认范围

Scope is always the first required selection after the action is clear.

Allowed options:

```
user
```
```
project
```
```
both
```

If scope is not explicit, ask only for scope and wait. When presenting choices, use a numbered list and allow the user to reply with either the number or the label.

Example:

text

Select a scope:
1. user
2. project
3. both

明确操作类型后，范围是第一个必填选项。

允许的选项：

```
user
```
（用户级）
```
project
```
（项目级）
```
both
```
（两者）

若范围不明确，仅询问范围并等待回复。展示选项时使用编号列表，允许用户通过编号或标签回复。

示例：

text

选择范围：
1. user（用户级）
2. project（项目级）
3. both（两者）

Step 2: Confirm source

步骤2：确认源

Check whether the user already specified sources.

Skip this step when the action is

remove

. Remove does not depend on source selection because it only acts on target-side symlinks.

If not, present a source list built from configuration:

all configured sources
```
all
```

Keep the list concrete. Include the default sources and any configured custom sources.

If source is not explicit, ask only for source and wait. Present the source list as a numbered list. Include

all

as one numbered option. Allow replies by number, label, or comma-separated multiple numbers if multi-select is needed.

检查用户是否已指定源。

若操作类型为

remove

，跳过此步骤。移除操作不依赖源选择，因为它仅作用于目标端的符号链接。

若未指定源，展示基于配置的源列表：

所有已配置的源
```
all
```
（全部）

列表需具体，包含默认源和所有已配置的自定义源。

若源不明确，仅询问源并等待回复。将源列表展示为编号列表，将

all

作为一个编号选项。允许用户通过编号、标签或逗号分隔的多个编号（若需多选）回复。

Step 3: Confirm skill

步骤3：确认Skill

Check whether the user already specified skill names.

If not, inspect the selected sources and present the available skills:

the concrete skill list from the selected sources
```
all
```

Do not ask for skills before source is known for

inventory

status

, and

sync

, because the skill list depends on the selected sources. For

remove

, ask for skills immediately after scope because source is not needed.

If skills are not explicit, ask only for skills and wait. Present the skill list as a numbered list. Include

all

as one numbered option. Allow replies by number, label, or comma-separated multiple numbers.

For

status

and

inventory

, skill selection is optional unless the user explicitly wants to narrow the inspection. If the user just wants a broad comparison and has already confirmed scope and source, you may inspect all skills in the selected sources. Do not ask for skill first in that scenario unless the user requested a filtered view.

检查用户是否已指定Skill名称。

若未指定，检查所选源并展示可用Skill：

所选源中的具体Skill列表
```
all
```
（全部）

对于

inventory

、

status

和

sync

操作，在明确源之前请勿询问Skill，因为Skill列表依赖于所选源。对于

remove

操作，确认范围后立即询问Skill，因为无需源信息。

若Skill不明确，仅询问Skill并等待回复。将Skill列表展示为编号列表，将

all

作为一个编号选项。允许用户通过编号、标签或逗号分隔的多个编号回复。

对于

status

和

inventory

操作，除非用户明确想要缩小检查范围，否则Skill选择为可选。若用户仅想要宽泛对比，且已确认范围和源，可检查所选源中的所有Skill，无需先询问Skill（除非用户要求过滤视图）。

Step 4: Confirm target agent

步骤4：确认目标Agent

Check whether the user already specified target agents.

If not, present the configured agent list:

all configured agents
```
all
```

If agents are not explicit, ask only for agents and wait. Present the agent list as a numbered list. Include

all

as one numbered option. Allow replies by number, label, or comma-separated multiple numbers.

For

status

, agent selection is also optional. If the user wants a broad comparison, you may inspect all configured agents after scope and source are confirmed. If the user wants only some agents, ask for that filter before running the status view.

检查用户是否已指定目标Agent。

若未指定，展示已配置的Agent列表：

所有已配置的Agent
```
all
```
（全部）

若Agent不明确，仅询问Agent并等待回复。将Agent列表展示为编号列表，将

all

作为一个编号选项。允许用户通过编号、标签或逗号分隔的多个编号回复。

对于

status

操作，Agent选择也为可选。若用户想要宽泛对比，确认范围和源后可检查所有已配置的Agent；若用户仅想要检查部分Agent，在运行状态视图前先询问筛选条件。

Step 5: Resolve source conflicts

步骤5：解决源冲突

If a selected skill exists in more than one selected source, stop and ask the user which source should win for that skill.

Do not choose automatically.

若所选Skill存在于多个所选源中，停止操作并询问用户该Skill应优先使用哪个源。

不得自动选择。

Step 6: Build the plan or status view

步骤6：生成计划或状态视图

After the required inputs are confirmed, build the dry-run plan or status view.

Required inputs by action:

```
inventory
```
: action, scope, source
```
status
```
: action, scope, source
```
sync
```
: action, scope, source, skill, agent
```
remove
```
: action, scope, skill, agent

Use the bundled script:

bash

bash scripts/sync_manager.sh inventory --sources cc-switch,agents --json

For broad status-first exploration, once action, scope, and source are confirmed, use

inventory

plan-status

to inspect the current state before asking the user to commit to a concrete sync or remove action.

bash

bash scripts/sync_manager.sh plan-status \
  --sources cc-switch,agents \
  --scope user \
  --tools claude-code,codex \
  --skills pdf,agent-browser \
  --project-root "$PWD" \
  --json

bash

bash scripts/sync_manager.sh plan-sync \
  --sources cc-switch,agents \
  --scope both \
  --tools claude-code,cursor \
  --skills pdf \
  --project-root "$PWD" \
  --source-choice pdf=cc-switch \
  --output /tmp/skill-sync.plan \
  --json

bash

bash scripts/sync_manager.sh plan-remove \
  --scope project \
  --tools cursor,codex \
  --skills agent-browser \
  --output /tmp/skill-remove.plan \
  --project-root "$PWD" \
  --json

收集完所有必要输入后，生成试运行计划或状态视图。

各操作所需的必要输入：

```
inventory
```
：操作类型、范围、源
```
status
```
：操作类型、范围、源
```
sync
```
：操作类型、范围、源、Skill、Agent
```
remove
```
：操作类型、范围、Skill、Agent

使用捆绑的脚本：

bash

bash scripts/sync_manager.sh inventory --sources cc-switch,agents --json

对于宽泛的"先查状态"场景，确认操作类型、范围和源后，先使用

inventory

或

plan-status

检查当前状态，再让用户确认具体的同步或移除操作。

bash

bash scripts/sync_manager.sh plan-status \
  --sources cc-switch,agents \
  --scope user \
  --tools claude-code,codex \
  --skills pdf,agent-browser \
  --project-root "$PWD" \
  --json

bash

bash scripts/sync_manager.sh plan-sync \
  --sources cc-switch,agents \
  --scope both \
  --tools claude-code,cursor \
  --skills pdf \
  --project-root "$PWD" \
  --source-choice pdf=cc-switch \
  --output /tmp/skill-sync.plan \
  --json

bash

bash scripts/sync_manager.sh plan-remove \
  --scope project \
  --tools cursor,codex \
  --skills agent-browser \
  --output /tmp/skill-remove.plan \
  --project-root "$PWD" \
  --json

Step 7: Present the plan or status summary

步骤7：展示计划或状态摘要

Before any apply step, present the plan clearly.

Always include:

action
scope
sources when applicable
skills
agents
source decisions for conflicts when applicable
planned commands or effects
skipped items and reasons

For

status

and

inventory

, use a structured explanation instead of an execution plan. The explanation must stay logical and easy to understand.

Default status presentation order:

action
scope
sources
inspected agents
```
Agent View
```
: which skills each agent is missing, linked, or externally covered by
```
Skill View
```
: which agents each key skill is present in, missing from, or covered externally by
```
Summary
```
: most complete agent, biggest gap, or main pattern
```
Next Suggestion
```
: the most sensible next sync step if the user wants to continue

When an external source covers a skill:

treat it as available in status output
do not count it as missing
do not create a redundant link during sync
if a redundant symlink already exists for the same externally loaded source, treat it as cleanup work instead of "correctly linked"

在执行任何应用步骤前，清晰展示计划。

必须包含以下内容：

操作类型
范围
适用的源
Skill
Agent
冲突源的决策（若有）
计划执行的命令或效果
跳过的项目及原因

对于

status

和

inventory

操作，使用结构化说明而非执行计划，说明必须逻辑清晰、易于理解。

默认状态展示顺序：

操作类型
范围
源
检查的Agent
```
Agent视图
```
：各Agent缺失、已链接或由外部源覆盖的Skill
```
Skill视图
```
：各关键Skill存在于哪些Agent、缺失于哪些Agent，或由外部源覆盖的情况
```
摘要
```
：覆盖最完整的Agent、最大差距或主要模式
```
下一步建议
```
：若用户继续操作，最合理的下一步同步步骤

当Skill由外部源覆盖时：

在状态输出中视为可用
不标记为缺失
同步时不创建冗余链接
若已存在指向同一外部加载源的冗余符号链接，将其视为需要清理的内容，而非"已正确链接"

Step 8: Wait for confirmation

步骤8：等待确认

If the user has not explicitly confirmed, stop.

Do not apply. Do not imply that dry-run already changed anything.

若用户未明确确认，停止操作。

请勿应用变更。请勿暗示试运行已产生任何变更。

Step 9: Execute

步骤9：执行

Only after explicit confirmation:

bash

bash scripts/sync_manager.sh apply --plan /tmp/skill-sync.plan --json

仅在获得明确确认后执行：

bash

bash scripts/sync_manager.sh apply --plan /tmp/skill-sync.plan --json

Interaction rules

交互规则

Ask one step at a time.
If scope is missing, ask only for scope.
If the action is
```
inventory
```
,
```
status
```
, or
```
sync
```
and scope is known but source is missing, ask only for source.
If the action is
```
remove
```
and scope is known but skill is missing, ask only for skill.
If the action is
```
sync
```
and source is known but skill is missing, ask only for skill.
If the action is
```
sync
```
or
```
remove
```
and skill is known but agent is missing, ask only for agent.
Do not batch unanswered questions together.
Do not scan skills before source is confirmed.
Do not ask for source during
```
remove
```
unless the user explicitly asks source-related diagnostic questions.
Do not pick
```
all
```
unless the user explicitly requested all.
If the user already provided a valid value, keep it and move to the next missing step.
For broad
```
status
```
or
```
inventory
```
requests, scope and source are the main gates. After they are confirmed, you may inspect all relevant skills and agents unless the user asked for narrower filters.
Whenever a list is shown, support both number-based replies and label-based replies.

一次仅询问一个步骤的问题。
若缺失范围，仅询问范围。
若操作类型为
```
inventory
```
、
```
status
```
或
```
sync
```
且范围已知但源缺失，仅询问源。
若操作类型为
```
remove
```
且范围已知但Skill缺失，仅询问Skill。
若操作类型为
```
sync
```
且源已知但Skill缺失，仅询问Skill。
若操作类型为
```
sync
```
或
```
remove
```
且Skill已知但Agent缺失，仅询问Agent。
不得批量询问未回答的问题。
在确认源之前，请勿扫描Skill。
除非用户明确询问源相关的诊断问题，否则在
```
remove
```
操作期间请勿询问源。
除非用户明确要求全部选项，否则请勿默认选择
```
all
```
。
若用户已提供有效值，保留该值并进入下一个缺失步骤。
对于宽泛的
```
status
```
或
```
inventory
```
请求，范围和源是核心条件。确认后，可检查所有相关Skill和Agent，除非用户要求更窄的筛选范围。
展示列表时，同时支持基于编号和标签的回复。

Handling conflicts and missing items

冲突与缺失项处理

If a requested skill is in none of the selected sources, report it as unavailable.
If a requested skill is in multiple selected sources, require a user choice.
If the status output contains
```
missing_by_tool
```
, use it for a gap-oriented answer.
If the status output contains
```
rows_by_tool
```
, use it for a concise per-tool summary.
Report partial success honestly.

若请求的Skill不存在于任何所选源中，报告该Skill不可用。
若请求的Skill存在于多个所选源中，要求用户选择优先级。
若状态输出包含
```
missing_by_tool
```
，使用该数据生成以差距为导向的回复。
若状态输出包含
```
rows_by_tool
```
，使用该数据生成简洁的按工具分类的摘要。
如实报告部分成功的情况。

Result summary format

结果摘要格式

After execution, always give the user a clear summary in this shape:

text

Action: sync
Scope: user
Sources: cc-switch
Skills: pdf, pptx
Agents: codex, cursor

Plan Summary
- create links: 4
- relink: 1
- covered by external source: 2
- skipped: 1

Result Summary
- linked successfully: 4
- relinked: 1
- cleaned redundant links: 1
- already correct: 2
- skipped: 1

Skipped Details
- cursor/pdf: target exists and is not a symlink

Next Notes
- no remaining conflicts
- no further confirmation needed

For

inventory

and

status

, keep the same logical structure:

what was inspected
```
Agent View
```
```
Skill View
```
summary conclusion
what needs user attention next

执行完成后，始终为用户提供清晰的摘要，格式如下：

text

操作：sync
范围：user
源：cc-switch
Skill：pdf, pptx
Agent：codex, cursor

计划摘要
- 创建链接：4
- 重新链接：1
- 由外部源覆盖：2
- 跳过：1

结果摘要
- 链接成功：4
- 已重新链接：1
- 清理冗余链接：1
- 已正确配置：2
- 跳过：1

跳过详情
- cursor/pdf：目标已存在且并非符号链接

后续说明
- 无剩余冲突
- 无需进一步确认

对于

inventory

和

status

操作，使用相同的逻辑结构：

检查内容
```
Agent视图
```
```
Skill视图
```
摘要结论
需要用户关注的后续事项

References

参考资料

Use bundled references instead of repeating long explanations inline:

```
references/path-model.md
```
```
references/operations.md
```
```
references/config.example.conf
```

使用捆绑的参考资料，而非重复冗长的内联说明：

```
references/path-model.md
```
```
references/operations.md
```
```
references/config.example.conf
```