Skill Selection

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.

Skills Are Guardrails

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. Determine the Required Capabilities

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. Gather Candidates

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. Evaluate Candidates

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. Install the Selected Skills

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. Update the Root Contract

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. Feed Insights Back

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

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
```
.

skill-selection

NPX Install

Tags

SKILL.md Content (Chinese)