skill-selection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Selection

Skillの導入を「良さそうなものを足す」作業にしない。目的は、projectに必要な能力ごとに、衝突しない担当を1つずつ決めることである。

Do not turn Skill adoption into a task of merely adding things that “look good.” The goal is to determine one non-conflicting owner for each capability required by the project.

Skillはガードレールである

Skills Are Guardrails

Skillは、agentが的外れな方向へ失敗するのを防ぐガードレールとして導入する。「当てはまるかもしれないから使う」ものではない。

発火する場面が明確で、その場面にちょうど当てはまるSkillだけを採用する。少しでも関係しそうなら起動する、という広いtriggerのSkillは採らない。
手順の量は、防ぐ失敗の大きさに比例させる。短い作業を長い儀式に変えるSkill（小さな修正にも毎回TDDや対話式のbrainstormingを強制するもの等）は採らないか、条件を絞った起動にする。
良いSkillは、防ぐ失敗の型と、その場面でだけ効く判断基準を短く持つ。一般的な心得の網羅は、agentが既定でできることの繰り返しになりやすい。

project-initには、選定の材料となる2つの表がある。

```
catalog/capabilities.tsv
```
— 能力の一覧。
```
scope
```
が
```
single
```
の能力は担当を1つに絞り、
```
multi
```
は併用してよい。
```
needed_when
```
はその能力が必要になる条件。
```
catalog/candidates.tsv
```
— 評価済みの候補記録。許可リストではない。前回までの評価結果をまとめたキャッシュであり、記録にないSkillも探索して評価してよい。

Introduce Skills as guardrails that prevent an agent from failing in the wrong direction. Do not introduce a Skill simply because it “might apply.”

Adopt only Skills whose activation scenario is clear and matches that scenario exactly. Do not adopt Skills with broad triggers that activate whenever there is even a slight relationship.
Scale the amount of procedure to the magnitude of the failure being prevented. Do not adopt Skills that turn short tasks into lengthy rituals, such as those that force full TDD or interactive brainstorming on every small fix. Instead, restrict their activation conditions.
A good Skill briefly describes the failure pattern it prevents and the judgment criteria that are effective only in that scenario. A catalog of general advice tends to duplicate what an agent can already do by default.

project-init provides two tables that serve as the basis for selection.

```
catalog/capabilities.tsv
```
— The capability list. A capability with
```
scope
```
set to
```
single
```
must have exactly one owner, while
```
multi
```
capabilities may be used together.
```
needed_when
```
indicates the conditions under which the capability is needed.
```
catalog/candidates.tsv
```
— Records of evaluated candidates. This is not an allowlist. It is a cache summarizing previous evaluation results, and Skills that are not recorded may also be discovered and evaluated.

1. 必要な能力を判定する

1. Determine the Required Capabilities

repositoryの実際の状態から、各能力の

needed_when

が成り立つかを判定する。たとえば、Cloudflareの設定があるか、test基盤があるか、日本語の文書があるか、などである。

一覧にない能力が必要なら、その能力を行として追加する候補にする（§6）。

Determine whether the

needed_when

condition for each capability is met based on the actual state of the repository. For example, determine whether Cloudflare is configured, whether a test infrastructure exists, or whether there are Japanese-language documents.

If a capability is needed but is not listed, consider adding it as a row (§6).

2. 候補を集める

2. Gather Candidates

能力ごとに、次の順で候補を集める。

projectに既にあるSkill（project-localの
```
skills/
```
や導入済みのもの）
```
candidates.tsv
```
で
```
default
```
の候補
```
candidates.tsv
```
の
```
alternative
```
の候補
外部の探索（
```
bunx skills find
```
、skills.sh、公式vendorのrepository、frameworkの公式docs）。候補repositoryの中身は
```
bunx skills add <source> --list
```
で確認できる

記録の

reviewed_on

が古い、または

review_depth

が

listed

skimmed

にとどまる候補は、その場で中身を読んでから判断する。記録は判断を省略する根拠にならない。

For each capability, gather candidates in the following order.

Skills already present in the project, including those in project-local
```
skills/
```
or already installed
The
```
default
```
candidate in
```
candidates.tsv
```
The
```
alternative
```
candidate in
```
candidates.tsv
```
External discovery through
```
bunx skills find
```
, skills.sh, official vendor repositories, and official framework documentation. The contents of a candidate repository can be inspected with
```
bunx skills add <source> --list
```

If a record's

reviewed_on

is outdated, or its

review_depth

is still

listed

skimmed

, read the contents before making a decision. A record is not a reason to skip evaluation.

3. 評価する

3. Evaluate Candidates

候補は中身を読んで評価する。descriptionだけで採用しない。

担当が重ならないか：同じ
```
single
```
能力に担当がすでにいれば、置き換えるか見送るかを決める。2つを併用しない。重なったSkillは、互いの指示を打ち消しあうか、片方が無視されるためである。
routerではないか：「応答の前に必ずSkillを確認せよ」「このpackのplaybookに従え」のように入口を握るSkillは導入しない。入口はprojectのroot contractだけが持つ。pack内の個別Skillは部品として使える。
前提が合うか：特定のIDE・plugin・pack固有の設定を前提にしていないか。userの承認待ちで自律実行を止めないか。
出所と条件：maintainer、license、更新状況、外部への通信やcommand実行の有無を確認する。licenseが再配布を禁じるSkillは、repositoryへcopyしない。
triggerの精度：descriptionが、起動すべき場面とそうでない場面を区別できるか。他のSkillのdescriptionと同じ場面を奪い合わないか。
費用：常時読まれる量と、起動時に読む量。防ぐ失敗に比べて重すぎないか。

迷う場合は、同じtaskをSkillあり・なしで実行して比べる（

policy-evaluation

の比較評価）。

Read the contents of each candidate and evaluate it. Do not adopt a candidate based only on its description.

Does ownership overlap? If a
```
single
```
capability already has an owner, decide whether to replace the existing owner or skip the candidate. Do not use both together. Overlapping Skills may cancel each other's instructions or cause one to be ignored.
Is it a router? Do not introduce Skills that control the entry point, such as “always check for Skills before responding” or “follow this pack's playbook.” Only the project's root contract owns the entry point. Individual Skills within a pack can be used as components.
Do the prerequisites fit? Check whether the Skill assumes a specific IDE, plugin, or pack-specific configuration, or whether it stops autonomous execution while waiting for user approval.
Provenance and conditions: Check the maintainer, license, update status, and whether the Skill communicates externally or executes commands. Do not copy a Skill into the repository if its license prohibits redistribution.
Trigger precision: Determine whether the description distinguishes between scenarios in which the Skill should and should not activate, and whether it competes with another Skill for the same scenario.
Cost: Consider the amount always loaded and the amount loaded upon activation. Determine whether this is too heavy relative to the failure being prevented.

When uncertain, execute the same task with and without the Skill and compare the results (

policy-evaluation

comparative evaluation).

4. 導入する

4. Install the Selected Skills

project-localに入れる。
```
--global
```
は使わない。
packを丸ごと入れず、
```
bunx skills add <source> --skill <name>
```
で個別に入れる。
```
--copy
```
で導入し、導入されたSkillのfileと
```
skills-lock.json
```
を両方commitする。
```
skills-lock.json
```
だけでは再現にならないためである。2026-10時点の
```
skills experimental_install
```
は、lockの
```
computedHash
```
と照合せずに配布元の現在の内容を取得し、導入先も
```
.agents/skills/
```
に固定される。
更新は
```
bunx skills update
```
で行い、Skill fileのdiffをPRで確認してから取り込む。配布元の変更を、確認せずに取り込まないためである。
導入した複製は直接編集しない。複製の内容は
```
computedHash
```
（各fileの相対pathと中身を、pathの大文字小文字を区別しない順に連結したsha256）と一致し続ける必要がある。project-initの
```
evals/policy-evaluation/vendored-skills-contract.sh
```
と同じ検査をprojectのquality gateに入れる。直したい点があれば、正本へPRを出す。
配布元がtagを付けているなら、
```
https://github.com/<owner>/<repo>/tree/<tag>
```
で導入してlockの
```
ref
```
をtagに固定する。commit SHAは
```
ref
```
に使えない。
licenseが再配布を禁じるSkillはcommitしない。
```
skills-lock.json
```
にだけ記録し、必要な環境で導入する。
```
disable-model-invocation: true
```
のSkill（
```
candidates.tsv
```
の
```
invocation
```
が
```
manual
```
）は、agentが自動では起動しない。採用する場合は、root contractの能力表に「この場面ではこのpathを読む」と明記する。

Install them project-locally. Do not use
```
--global
```
.
Do not install an entire pack. Install individual Skills with
```
bunx skills add <source> --skill <name>
```
.
Install with
```
--copy
```
, and commit both the installed Skill files and
```
skills-lock.json
```
.
```
skills-lock.json
```
alone cannot reproduce the installation. As of 2026-10,
```
skills experimental_install
```
retrieves the current contents from the distribution source without comparing them against the lock file's
```
computedHash
```
, and the installation destination is fixed to
```
.agents/skills/
```
.
Perform updates with
```
bunx skills update
```
. Review the Skill file diff in a PR before merging it. This prevents changes from the distribution source from being incorporated without review.
Do not directly edit an installed copy. Its contents must continue to match
```
computedHash
```
, which is the sha256 of each file's relative path and contents concatenated in case-insensitive path order. Add the same check used by project-init's
```
evals/policy-evaluation/vendored-skills-contract.sh
```
to the project's quality gate. If a change is needed, open a PR against the canonical source.
If the distribution source has a tag, install it from
```
https://github.com/<owner>/<repo>/tree/<tag>
```
and pin the lock file's
```
ref
```
to the tag. A commit SHA cannot be used for
```
ref
```
.
Do not commit Skills whose licenses prohibit redistribution. Record them only in
```
skills-lock.json
```
and install them in the environments where they are needed.
A Skill with
```
disable-model-invocation: true
```
, corresponding to
```
manual
```
in the
```
invocation
```
column of
```
candidates.tsv
```
, will not be invoked automatically by the agent. If adopting it, explicitly state in the root contract's capability table: “Read this path in this situation.”

5. root contractへ反映する

5. Update the Root Contract

root contractのSkill一覧は、能力ごとの担当表として書く。採用したSkillの名前、使う場面、手動起動ならそのpathを並べる。外部Skillも自作Skillも同じ表に載せる。

見送った候補や除外したrouterは、root contractに書かない。理由はproject内の決定記録（ADR等）に残す。

Write the root contract's Skill list as an ownership table for each capability. Include the adopted Skill's name, when it should be used, and its path if it is invoked manually. List external and custom Skills in the same table.

Do not write rejected candidates or excluded routers to the root contract. Record the reasons in a project decision record, such as an ADR.

6. 知見を還元する

6. Feed Insights Back

project固有でない評価結果は、project-initの

catalog/

へ戻す。

新しく評価した候補や、採否を変えた候補は
```
candidates.tsv
```
を更新する。
```
reviewed_rev
```
と
```
reviewed_on
```
は、実際に読んだrevisionと日付にする。
新しい能力が必要になったら
```
capabilities.tsv
```
に行を足す。
変更はproject-initへのPRとして出す。採用中のprojectから直接書き換えない。

Return evaluation results that are not specific to a single project to project-init's

catalog/

Update
```
candidates.tsv
```
for newly evaluated candidates or candidates whose adoption status has changed. Set
```
reviewed_rev
```
and
```
reviewed_on
```
to the revision and date that were actually reviewed.
If a new capability is needed, add a row to
```
capabilities.tsv
```
.
Submit changes as a PR to project-init. Do not directly modify it from a project that has adopted the Skills.

記録の値

Recorded Values

candidates.tsv

の列の意味は次のとおりである。

```
status
```
：
```
default
```
（その能力の標準の担当）、
```
alternative
```
（担当の代替。併用はしない）、
```
reference
```
（導入せず考え方だけを参照）、
```
watch
```
（評価や改善の途中）、
```
excluded
```
（導入しない）
```
review_depth
```
：
```
listed
```
（存在と説明だけを確認）、
```
skimmed
```
（主要部分を読んだ）、
```
read
```
（全体を読んだ）、
```
evaluated
```
（比較評価まで行った）
```
invocation
```
：
```
auto
```
（descriptionで自動起動）、
```
manual
```
（明示的に呼ぶかpathで読ませる必要がある）
skill列の
```
*
```
は、package全体や複数Skillをまとめた記録を表す。
```
default
```
には使えない。

The columns in

candidates.tsv

have the following meanings.

```
status
```
:
```
default
```
(the standard owner for the capability),
```
alternative
```
(a replacement owner; not used together with the default),
```
reference
```
(not installed; only its ideas are referenced),
```
watch
```
(still being evaluated or improved),
```
excluded
```
(not installed)
```
review_depth
```
:
```
listed
```
(only the existence and description were verified),
```
skimmed
```
(the main sections were read),
```
read
```
(the entire contents were read),
```
evaluated
```
(comparative evaluation was performed)
```
invocation
```
:
```
auto
```
(activated automatically based on the description),
```
manual
```
(must be explicitly invoked or read by path)
A
```
*
```
in the
```
skill
```
column indicates a record covering an entire package or multiple Skills. It cannot be used with
```
default
```
.