distribute-skill-to-all-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Distribute a Skill Across All Agents

在所有Agent间分发Skill

The user has 4 agent skill locations on their MacBook. A skill must exist in each (or via symlink) to be discoverable by every agent.

用户的MacBook上有4个Agent技能存储位置。一个技能必须存在于每个位置（或通过符号链接关联）才能被所有Agent发现。

The 4 Canonical Locations

4个标准存储位置

Agent	Skills Folder	Notes
Codex / OpenAI Agents	`~/.agents/skills/`	Canonical — author skills here first
Claude Code	`~/.claude/skills/`	Symlink → `~/.agents/skills/` — writing to `.agents/skills` automatically covers Claude
Pi Agent	`~/.pi/agent/skills/`	Symlink → `~/.agents/skills/` — auto-covered. (Path is `/agent/` nested — NOT `~/.pi/skills/` )
Hermes Agent	`~/.hermes/skills/`	Independent copy — the only one needing a manual copy

Agent	技能文件夹	说明
Codex / OpenAI Agents	`~/.agents/skills/`	标准位置 — 优先在此处编写技能
Claude Code	`~/.claude/skills/`	符号链接指向 `~/.agents/skills/` — 写入 `.agents/skills` 会自动同步到Claude
Pi Agent	`~/.pi/agent/skills/`	符号链接指向 `~/.agents/skills/` — 自动同步。（路径为嵌套的 `/agent/` — 并非 `~/.pi/skills/` ）
Hermes Agent	`~/.hermes/skills/`	独立副本 — 是唯一需要手动复制的位置

Workflow

操作流程

Author the skill in
~/.agents/skills/<skill-name>/SKILL.md
(canonical). Follow

effective-agent-skills

SKILL.md guidance.

Verify the
.claude
symlink is intact (one-time check):
bash
```
ls -la ~/.claude/skills
# Expect: ~/.claude/skills -> ~/.agents/skills
```
If it's a real directory instead of a symlink, the user has diverged copies — ask before touching.

Copy to
.hermes
only (

.claude

and

.pi

are symlinks — already covered):

bash

SKILL=<skill-name>
cp -r ~/.agents/skills/$SKILL ~/.hermes/skills/

Verify all 4 locations show identical byte counts:

bash

for p in ~/.agents/skills/$SKILL ~/.claude/skills/$SKILL ~/.pi/agent/skills/$SKILL ~/.hermes/skills/$SKILL; do
  echo "$p: $(wc -c < $p/SKILL.md) bytes"
done

All four numbers must match. If

.claude

.pi

shows a different byte count, that symlink is broken — investigate before proceeding.

在
~/.agents/skills/<skill-name>/SKILL.md
中编写技能（标准位置）。遵循
```
effective-agent-skills
```
的SKILL.md编写规范。
验证
.claude
的符号链接是否完整（一次性检查）：
bash
```
ls -la ~/.claude/skills
# 预期结果：~/.claude/skills -> ~/.agents/skills
```
如果它是真实目录而非符号链接，说明用户的副本已不一致 — 修改前需询问用户。

仅复制到
.hermes
（

.claude

和

.pi

为符号链接 — 已自动同步）：

bash

SKILL=<skill-name>
cp -r ~/.agents/skills/$SKILL ~/.hermes/skills/

验证4个位置的文件字节数是否一致：

bash

for p in ~/.agents/skills/$SKILL ~/.claude/skills/$SKILL ~/.pi/agent/skills/$SKILL ~/.hermes/skills/$SKILL; do
  echo "$p: $(wc -c < $p/SKILL.md) bytes"
done

四个数值必须完全匹配。如果

.claude

或

.pi

显示不同的字节数，说明符号链接已损坏 — 需先排查问题再继续。

Updating an Existing Distributed Skill

更新已分发的技能

Same flow — re-copy from

~/.agents/skills/

.hermes/skills/

. The

.claude

and

.pi

symlinks update automatically.

cp -r

overwrites by default; use

rsync -a --delete

if the skill folder has nested files that may have been removed:

bash

rsync -a --delete ~/.agents/skills/$SKILL/ ~/.hermes/skills/$SKILL/

流程相同 — 从

~/.agents/skills/

重新复制到

.hermes/skills/

。

.claude

和

.pi

的符号链接会自动更新。默认情况下

cp -r

会覆盖文件；如果技能文件夹包含可能已被删除的嵌套文件，可使用

rsync -a --delete

：

bash

rsync -a --delete ~/.agents/skills/$SKILL/ ~/.hermes/skills/$SKILL/

Pitfalls

注意事项

~/.pi/skills/
is the wrong location. Pi Agent loads from
```
~/.pi/agent/skills/
```
only. A skill placed in
```
~/.pi/skills/
```
is invisible. If you find skills already there, they're orphans — confirm with the user before deleting.
~/.claude/skills
is a symlink, not a folder.
```
cp -r ~/.agents/skills/foo ~/.claude/skills/
```
will error with "are identical". Skip the explicit Claude copy.
Project-local skills exist too —
```
./.pi/agent/skills/
```
(or
```
.pi/skills/
```
) inside a repo overrides the global one on collision (later-discovered wins). This skill only handles GLOBAL distribution.
.pi/agent/skills
is a symlink →
.agents/skills
. Don't
```
cp
```
into it (errors "are identical"); it auto-syncs. Only
```
.hermes/skills
```
is an independent copy — don't unilaterally consolidate Hermes into a symlink unless the user asks.
Hermes snapshots skills at session start. A newly-distributed skill won't appear inside a running Hermes session until restart (it works fine for future sessions and for the other 3 agents immediately).
Filename casing matters on case-sensitive volumes.
```
SKILL.md
```
must be uppercase.

~/.pi/skills/
是错误的位置。Pi Agent仅从
```
~/.pi/agent/skills/
```
加载技能。放置在
```
~/.pi/skills/
```
中的技能将无法被识别。如果发现已有技能在此处，它们属于无效文件 — 删除前需与用户确认。
~/.claude/skills
是符号链接，而非文件夹。执行
```
cp -r ~/.agents/skills/foo ~/.claude/skills/
```
会报错“文件相同”。需跳过对Claude的显式复制操作。
也存在项目本地技能 — 仓库内的
```
./.pi/agent/skills/
```
（或
```
.pi/skills/
```
）在发生冲突时会覆盖全局技能（后被发现的优先）。本指南仅处理全局分发。
.pi/agent/skills
是指向
.agents/skills
的符号链接。不要向其中复制文件（会报错“文件相同”）；它会自动同步。只有
```
.hermes/skills
```
是独立副本 — 除非用户要求，否则不要单方面将Hermes合并为符号链接。
Hermes会在会话启动时快照技能。新分发的技能在运行中的Hermes会话中不会显示，直到重启（对未来会话和其他3个Agent会立即生效）。
在区分大小写的卷上，文件名大小写至关重要。
```
SKILL.md
```
必须为大写。

When NOT to Use This Skill

不适用本指南的场景

Skill is project-specific → put it in
```
./.claude/skills/
```
,
```
./.pi/agent/skills/
```
, etc. inside the repo, not globally.
Editing one agent's skill only (e.g. a Hermes-only workflow) → patch that file directly, don't propagate.
Removing a skill globally →
```
rm -rf
```
from
```
~/.agents/skills/
```
(covers
```
.claude
```
+
```
.pi
```
symlinks) and from
```
~/.hermes/skills/
```
(and confirm with the user first; deletion is destructive).

技能为项目专属 → 将其放置在仓库内的
```
./.claude/skills/
```
、
```
./.pi/agent/skills/
```
等位置，而非全局位置。
仅编辑单个Agent的技能（例如仅适用于Hermes的工作流） → 直接修改该文件，不要传播更改。
全局删除技能 → 从
```
~/.agents/skills/
```
中执行
```
rm -rf
```
（会同步删除
```
.claude
```
和
```
.pi
```
符号链接指向的内容），并从
```
~/.hermes/skills/
```
中删除（删除前需与用户确认；此操作具有破坏性）。