shunk031-manage-public-private-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage Public and Private Skills

管理公开与私有技能

Skill content lives in two dedicated repositories. Neither dotfiles repository holds it any more, so a request to change a skill is a request to change one of these, not the checkout you are probably standing in.

技能内容存储在两个专用仓库中。dotfiles 仓库不再存储技能内容，因此更改技能的请求意味着要修改这两个专用仓库之一，而非你当前所在的检出仓库。

Where a skill lives

技能存储位置

Repository	Holds
`shunk031/skills`	Every publishable skill
`shunk031/skills-private`	Skills whose body names an internal host, a credential, an internal endpoint, or an org-internal process
`shunk031/dotfiles`	The subscription allowlist and the reconcile script. No skill content
`shunk031/dotfiles-private`	No skill content

The deciding test is that single question about the skill body. Being written for work does not make a skill private; naming an internal system does. When a skill is close to the line, prefer private and say why.

仓库名称	存储内容
`shunk031/skills`	所有可发布的技能
`shunk031/skills-private`	技能内容涉及内部主机、凭证、内部端点或组织内部流程的技能
`shunk031/dotfiles`	订阅白名单和协调脚本。不存储技能内容
`shunk031/dotfiles-private`	不存储技能内容

判断标准仅围绕技能内容本身：为工作场景编写并不意味着技能属于私有，只有涉及内部系统时才归为私有。当技能归属存疑时，优先归类为私有并说明原因。

Routing a request

请求路由流程

Identify the skill by name.
```
~/.agents/skills/<name>
```
is the installed copy; it tells you the skill exists, not where its source is.
Decide the owning repository with the test above, or by checking which repository already contains it.
Work in a task worktree of that repository. Never edit the installed copy.
If the change spans both skill repositories, keep the worktrees, commits, and pull requests separate and state the ordering between them.

通过名称识别技能。
```
~/.agents/skills/<name>
```
是已安装的副本，仅用于确认技能存在，无法体现其源码位置。
根据上述判断标准或查看现有存储情况，确定技能所属仓库。
在该仓库的任务工作树中开展工作。切勿编辑已安装的副本。
若变更涉及两个技能仓库，需保持工作树、提交记录和拉取请求相互独立，并说明执行顺序。

Never edit the installed copy

切勿编辑已安装的副本

~/.agents/skills/<name>

is a real directory that the

skills

CLI writes. It is a copy, not a link to any source, so edits there are silently discarded by the next

skills update

This differs from the old arrangement, where the pool entry was a symlink into the chezmoi source tree and editing the live skill did edit the source.

~/.agents/skills/<name>

是由

skills

CLI 生成的真实目录。它是一份副本而非指向源码的链接，因此对其进行的编辑会在下次

skills update

时被静默覆盖。

这与旧机制不同：旧机制中，技能池条目是指向 chezmoi 源码树的符号链接，编辑已安装的技能等同于编辑源码。

The loop from edit to running skill

从编辑到技能生效的流程

edit in the skill repository worktree
  → gates pass locally
  → pull request
  → merge
  → chezmoi apply on the machine, which runs skills add/update

chezmoi apply

throttles

skills update

to once a day so that a file-watch loop does not fetch on every save. Right after merging, force it:

bash

DOTFILES_SKILLS_FORCE_UPDATE=1 chezmoi apply    # or: make skills-update

Adding or removing a skill from the allowlist is a change to

install/common/skills.sh

shunk031/dotfiles

, and it belongs in its own pull request there, separate from the skill's own.

在技能仓库工作树中编辑
  → 本地通过校验门限
  → 创建拉取请求
  → 合并请求
  → 在机器上执行 chezmoi apply，触发 skills add/update

chezmoi apply

会将

skills update

的频率限制为每天一次，避免文件监听循环在每次保存时都触发拉取操作。合并请求后可强制执行更新：

bash

DOTFILES_SKILLS_FORCE_UPDATE=1 chezmoi apply    # 或执行：make skills-update

在白名单中添加或移除技能属于对

shunk031/dotfiles

仓库中

install/common/skills.sh

的修改，需单独创建拉取请求，与技能自身的变更请求分离。

Layout rules that are easy to get wrong

易出错的布局规则

One directory per skill at
```
skills/<name>/
```
, holding
```
SKILL.md
```
. Frontmatter
```
name
```
must equal the directory name.
Never put a
```
SKILL.md
```
at a repository root. The
```
skills
```
CLI stops discovery there and returns only that skill, hiding every other one from installers.
Never nest a skill deeper than
```
skills/<name>/
```
.
```
evals/
```
is reserved: shuhari looks for
```
evals/evals.json
```
and
```
evals/triggers.json
```
at fixed paths.
Never commit
```
skills/<name>-workspace/
```
. Those are shuhari run artifacts holding verbatim agent transcripts.
Scripts a skill needs at runtime go inside the skill directory. The CLI copies the whole skill directory into the pool, so anything outside it will not be there when the skill runs.

每个技能对应一个
```
skills/<name>/
```
目录，目录下包含
```
SKILL.md
```
。文件头的
```
name
```
必须与目录名称一致。
切勿在仓库根目录放置
```
SKILL.md
```
。
```
skills
```
CLI 会在此处停止技能发现，仅返回该技能，导致其他技能无法被安装者识别。
技能目录的嵌套深度不得超过
```
skills/<name>/
```
。
```
evals/
```
目录为保留目录：shuhari 会在固定路径查找
```
evals/evals.json
```
和
```
evals/triggers.json
```
。
切勿提交
```
skills/<name>-workspace/
```
目录。这些是 shuhari 的运行产物，包含 Agent 的完整交互记录。
技能运行时所需的脚本需放在技能目录内。CLI 会将整个技能目录复制到技能池，因此目录外的文件无法在技能运行时被调用。

Writing evals

编写评估用例

Behavior cases go in

evals/evals.json

, each with

id

prompt

, and

expected_output

;

assertions

and

files

are optional. Trigger cases go in

evals/triggers.json

and need at least one positive and one near-miss negative control.

Write

expected_output

as one to three sentences describing the behaviour that should result, not the wording of a good reply, and do not restate the assertions. Shuhari runs a blind A/B comparator between the with-skill and without-skill outputs alongside assertion grading, so

expected_output

that echoes assertion text biases that comparison.

Make negative controls near misses. A control that shares the skill's vocabulary while genuinely not calling for it measures the boundary; an unrelated prompt measures nothing.

Runs are offline by default. A skill whose subject is the live network cannot be graded offline: it correctly refuses to proceed and loses to a baseline that guesses. Declare the exception with an

evals/network-required

marker.

Order of work is

--validate-only

, then

shuhari check trigger

, then

shuhari eval skill

. The first is instant and offline; the last runs both arms plus a grader and a comparator.

行为用例需放在

evals/evals.json

中，每个用例包含

id

、

prompt

和

expected_output

；

assertions

和

files

为可选字段。触发用例需放在

evals/triggers.json

中，至少包含一个正向用例和一个近似误判的反向用例。

expected_output

应使用1-3句话描述预期的行为结果，而非回复的措辞，且不要重复断言内容。Shuhari 会在评估时对启用技能和未启用技能的输出进行盲态 A/B 对比，若

expected_output

与断言文本重复，会影响对比结果的公正性。

反向用例需设置为近似场景。与技能词汇相似但确实不需要调用技能的用例可测试边界；无关的提示无法起到测试作用。

默认情况下，评估运行在离线环境。若技能涉及实时网络，离线评估会因技能正确拒绝执行而输给基线猜测结果。此时需通过

evals/network-required

标记声明例外情况。

工作顺序为：先执行

--validate-only

，再执行

shuhari check trigger

，最后执行

shuhari eval skill

。第一步为即时离线校验；最后一步会同时运行两组测试、评估器和对比器。

Authoring and reviewing a skill

技能编写与评审

Write one

SKILL.md

. Do not create per-agent variants: a global install keeps a single canonical copy at

~/.agents/skills/<name>

and points each agent at it.

Review the draft with both agents' skill-creation skills, because they disagree usefully:

Claude Code:
```
/skill-creator
```

Codex:

$skill-creator

(its built-in, at

~/.codex/skills/.system/skill-creator

)

编写单个

SKILL.md

文件。无需为不同 Agent 创建变体：全局安装会在

~/.agents/skills/<name>

保留一份标准副本，并让所有 Agent 指向该副本。

使用两款 Agent 的技能创建工具评审草稿，它们的差异具有参考价值：

Claude Code：
```
/skill-creator
```

Codex：

$skill-creator

（内置工具，路径为

~/.codex/skills/.system/skill-creator

）

Before finishing

完成前的检查

Run the owning repository's gates and report which repository owns each change. Keep credential values out of command output, quoted diffs, and summaries — this matters in the private repository, where eval prompts are committed in plaintext and must use placeholders.

Creating or updating a pull request is part of ordinary work. Merging, running

chezmoi apply

, and changing runtime state are not: ask first.

运行所属仓库的校验门限，并说明每项变更所属的仓库。确保凭证值不出现在命令输出、带引号的差异内容和摘要中——这在私有仓库中尤为重要，因为评估用例的提示会以明文提交，必须使用占位符。

创建或更新拉取请求属于常规工作内容。合并请求、执行

chezmoi apply

和更改运行时状态不属于常规工作，需先征得同意。