refresh-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

refresh-skills

方針

Policy

philtzjp/skills のスキルは、各メンバーのホームに

npx skills

で導入します。作業対象リポジトリにはコピーしません。コピーした時点から古くなり、上流の更新が届かなくなるためです。

作業の入口は https://raw.githubusercontent.com/philtzjp/startingpoint/main/START.md です。導入するスキルの選び方は skill-selection に従ってください。

以前は各リポジトリの

.agents/skills/

にスキルをコピーし、上流と同期していました。この手順はもう使いません。

The skills in philtzjp/skills are installed in each team member's home directory with

npx skills

. They are not copied into the target repository. Otherwise, the copies become outdated from the moment they are installed and stop receiving upstream updates.

The entry point for work is https://raw.githubusercontent.com/philtzjp/startingpoint/main/START.md . Follow skill-selection when choosing which skills to install.

Previously, skills were copied into each repository's

.agents/skills/

directory and kept in sync with upstream. This procedure is no longer used.

ホームのスキルを最新にする

Updating skills in the home directory

作業を始めるたびに、導入済みのスキルを確認します。

DISABLE_TELEMETRY=1 npx skills list -g

Source が philtzjp/skills のスキルを、名前を指定して更新します。

DISABLE_TELEMETRY=1 npx skills update <スキル名> <スキル名> -g -y

名前を指定し、ユーザーが他の Source から入れたスキルには触れない。
必要なスキルが入っていない、または Source が philtzjp/skills 以外なら、ユーザーの許可を得てから導入し直す。手順は skill-selection に書いてある。
導入や更新ができなければ、推測で進めずにユーザーに報告する。

Check the installed skills every time you begin work.

DISABLE_TELEMETRY=1 npx skills list -g

Update skills whose Source is philtzjp/skills by specifying their names.

DISABLE_TELEMETRY=1 npx skills update <skill-name> <skill-name> -g -y

Specify the names so that skills installed by the user from other Sources are not modified.
If a required skill is not installed, or its Source is not philtzjp/skills, reinstall it after obtaining the user's permission. Follow the procedure in skill-selection.
If installation or updating is not possible, report the issue to the user instead of proceeding based on assumptions.

作業対象リポジトリに残ったコピーを移行する

Migrating copies left in the target repository

作業対象リポジトリの

.agents/skills/

と

.claude/skills/

を確認し、philtzjp/skills と同名のスキルがあれば、次の手順で移行を提案します。移行は github スキルの手順で PR にします。ユーザーの確認なしに削除しないでください。

上流にあるスキルの一覧は次で取得できます。

DISABLE_TELEMETRY=1 npx skills add philtzjp/skills --list

Check the target repository's

.agents/skills/

and

.claude/skills/

directories. If a skill with the same name exists in philtzjp/skills, propose the following migration procedure. Perform the migration in a PR by following the github skill. Do not delete anything without the user's confirmation.

The list of available upstream skills can be obtained with the following command:

DISABLE_TELEMETRY=1 npx skills add philtzjp/skills --list

1. コピーを分類する

1. Classify the copies

上流と同じ内容のコピー：削除してよい。
上流で統合済みの旧スキル：削除してよい。統合先は次のとおり。

旧スキル統合先
commit-and-git、issue-branch-pr-flow github
japanese-writing japanese
typescript-monorepo turborepo
api-design hono
data-migration db
e2e-testing e2etest
google-analytics analytics
上流と内容が違うコピー：ローカルで改変されている可能性がある。削除する前に差分をユーザーに見せる。
sh
```
curl -fsSL https://raw.githubusercontent.com/philtzjp/skills/main/.agents/skills/<スキル名>/SKILL.md | diff - .agents/skills/<スキル名>/SKILL.md
```
上流が古い版のまま改変されただけか、そのリポジトリ固有の事情による改変かをユーザーと判断する。他のリポジトリにも役立つ改変なら、skill-escalation に従って philtzjp/skills に提案する。そのリポジトリだけの事情なら、リポジトリ固有のスキルとして残すか、AGENTS.md に規約として書く。
philtzjp/skills にないスキル：リポジトリ固有のスキル。残す。

旧スキル	統合先
commit-and-git、issue-branch-pr-flow	github
japanese-writing	japanese
typescript-monorepo	turborepo
api-design	hono
data-migration	db
e2e-testing	e2etest
google-analytics	analytics

A copy with the same content as upstream: It is safe to delete.
An old skill that has been merged upstream: It is safe to delete. The merge destinations are as follows.

Old skill Merge destination
commit-and-git、issue-branch-pr-flow github
japanese-writing japanese
typescript-monorepo turborepo
api-design hono
data-migration db
e2e-testing e2etest
google-analytics analytics
A copy whose content differs from upstream: It may have been modified locally. Show the user the differences before deleting it.
sh
```
curl -fsSL https://raw.githubusercontent.com/philtzjp/skills/main/.agents/skills/<skill-name>/SKILL.md | diff - .agents/skills/<skill-name>/SKILL.md
```
Have the user determine whether the copy was merely modified from an older upstream version or whether the changes are specific to that repository. If the changes would also be useful in other repositories, propose them to philtzjp/skills in accordance with skill-escalation. If they are specific only to that repository, retain the skill as a repository-specific skill or write the convention in AGENTS.md.
A skill that does not exist in philtzjp/skills: It is a repository-specific skill. Retain it.

Old skill	Merge destination
commit-and-git、issue-branch-pr-flow	github
japanese-writing	japanese
typescript-monorepo	turborepo
api-design	hono
data-migration	db
e2e-testing	e2etest
google-analytics	analytics

2. 移行する

2. Perform the migration

削除するスキル、または統合先のスキルが、ホームに導入されているか確認する。入っていなければ、ユーザーの許可を得て導入する。

削除するスキルの

.agents/skills/<スキル名>/

と

.claude/skills/<スキル名>

を削除する。

AGENTS.md や CLAUDE.md のスキル表から、削除したスキルの行を消す。リポジトリ固有のスキルが残らなければ、スキル表ごと消す。
AGENTS.md や CLAUDE.md の中で、削除したスキルを前提にした記述（「philtzjp/skills から取り込む」「refresh-skills で同期する」など）を消す。

AGENTS.md に、philtzjp/startingpoint の START.md を読む案内を入れる。

markdown

## 開発ルール

作業を始める前に、https://raw.githubusercontent.com/philtzjp/startingpoint/main/START.md を curl で取得して全文を読み、書かれている手順に従ってください。

philtzjp/startingpoint 由来の
```
scripts/refresh-skills.sh
```
や
```
.cursor/environment.json
```
のように、コピーの同期を前提にした仕組みがあれば、
```
npx skills
```
に置き換えるようユーザーに提案する。
- ```
scripts/refresh-skills.sh
```
  ：上流との差分確認（
```
--upstream
```
  ）とコピーの同期をやめ、
```
npx skills update
```
  でホームのスキルを更新する内容にする。リポジトリ固有のスキルが残るなら、シンボリックリンクとスキル表の突き合わせだけを残す。残らなければ、スクリプトごと削除する。
- ```
.cursor/environment.json
```
  の
```
start
```
  ：Cursor Cloud Agent は起動のたびにホームが空になるので、
```
./scripts/refresh-skills.sh
```
  の代わりに、起動時にスキルを導入する。
  json
```
{
  "start": "DISABLE_TELEMETRY=1 npx skills add philtzjp/skills -g -a cursor -s github -s japanese -s turborepo -y"
}
```
- 他にも、CI、lefthook、セットアップ用のスクリプトなどでスキルのコピーや同期をしている箇所があれば、同じく
```
npx skills
```
  に置き換える。

Check whether the skill being deleted or its merge destination is installed in the home directory. If it is not installed, obtain the user's permission and install it.

Delete

.agents/skills/<skill-name>/

and

.claude/skills/<skill-name>

for each skill being deleted.

Remove the rows for deleted skills from the skill tables in AGENTS.md and CLAUDE.md. If no repository-specific skills remain, remove the entire skill table.
Remove statements in AGENTS.md and CLAUDE.md that assume the deleted skills still exist, such as “imported from philtzjp/skills” or “synchronized with refresh-skills.”

Add an instruction to AGENTS.md to read the START.md file from philtzjp/startingpoint.

markdown

## Development Rules

Before starting work, use curl to retrieve the following URL, read the entire file, and follow the procedures it contains:
https://raw.githubusercontent.com/philtzjp/startingpoint/main/START.md

If there are mechanisms derived from philtzjp/startingpoint, such as
```
scripts/refresh-skills.sh
```
or
```
.cursor/environment.json
```
, that assume copied skills are synchronized, propose replacing them with
```
npx skills
```
.
- ```
scripts/refresh-skills.sh
```
  : Stop checking differences with upstream using
```
--upstream
```
  and stop synchronizing copies. Change the script to update skills in the home directory with
```
npx skills update
```
  . If repository-specific skills remain, retain only the symlink and skill-table reconciliation. If none remain, delete the script entirely.
- The
```
start
```
  setting in
```
.cursor/environment.json
```
  : Cursor Cloud Agent's home directory is empty every time it starts, so install the skills at startup instead of running
```
./scripts/refresh-skills.sh
```
  .
  json
```
{
  "start": "DISABLE_TELEMETRY=1 npx skills add philtzjp/skills -g -a cursor -s github -s japanese -s turborepo -y"
}
```
- If other mechanisms, such as CI, lefthook, or setup scripts, copy or synchronize skills, replace them with
```
npx skills
```
  in the same way.

スキルの正本とシンボリックリンクを突き合わせる

Reconciling canonical sources and symlinks

リポジトリ固有のスキルがあるリポジトリと、philtzjp/skills 本体では、次の 4 つが一致している必要があります。

```
.agents/skills/<スキル名>/SKILL.md
```
（正本）

.claude/skills/<スキル名>

（

../../.agents/skills/<スキル名>

への相対シンボリックリンク）

AGENTS.md のスキル表の行
SKILL.md の frontmatter の
```
name
```

確認すること。

正本は
```
.agents/skills/
```
に置く。
```
.claude/skills/
```
の下に実ファイルを置かない。
シンボリックリンクは相対パスにする。絶対パスにしない。
リンク切れがない。対応するリンクが欠けていない。
スキル表とディレクトリの集合が一致している。
スキル名は kebab-case。frontmatter の
```
name
```
がディレクトリ名と一致している。
スキル本体に機密情報、トークン、認証情報を書いていない。

直し方。

リンクが欠けている：

ln -s ../../.agents/skills/<スキル名> .claude/skills/<スキル名>

リンクが実ファイル、または別の場所を指している：削除して作り直す。
リンク先がない：リンクを削除する。
スキル表とディレクトリがずれている：表の行を足すか消す。
```
name
```
がディレクトリ名と違う：frontmatter を直す。

直したら、もう一度突き合わせて一致を確認してください。

In repositories that contain repository-specific skills and in the philtzjp/skills repository itself, the following four items must be consistent:

```
.agents/skills/<skill-name>/SKILL.md
```
(the canonical source)

.claude/skills/<skill-name>

(a relative symlink to

../../.agents/skills/<skill-name>

)

The corresponding row in the skill table in AGENTS.md
The
```
name
```
field in the SKILL.md frontmatter

Check the following:

The canonical source is located under
```
.agents/skills/
```
. Do not place regular files under
```
.claude/skills/
```
.
Symlinks use relative paths, not absolute paths.
There are no broken symlinks or missing corresponding links.
The set of skills in the skill table matches the set of skill directories.
Skill names use kebab-case, and the frontmatter
```
name
```
matches the directory name.
The skill does not contain sensitive information, tokens, or credentials.

To fix an issue:

If a link is missing:

ln -s ../../.agents/skills/<skill-name> .claude/skills/<skill-name>

If a link is a regular file or points to a different location: delete it and recreate it.
If the link target does not exist: delete the link.
If the skill table and directories do not match: add or remove the corresponding table rows.
If
```
name
```
differs from the directory name: correct the frontmatter.

After making the corrections, reconcile and verify the items again.

スキルを追加・削除・リネームする

Adding, deleting, or renaming skills

リポジトリ固有のスキル、または philtzjp/skills 本体のスキルを変えるときの手順です。

追加：
```
.agents/skills/<スキル名>/SKILL.md
```
を作り、frontmatter に
```
name
```
と
```
description
```
（どんな場面で使うかを具体的に書く）を入れる。シンボリックリンクを作り、スキル表に行を足す。
削除：ディレクトリ、シンボリックリンク、スキル表の行を消す。他のスキルや AGENTS.md からの参照も探して直す。
リネーム：ディレクトリ名と frontmatter の
```
name
```
を変え、シンボリックリンクを作り直し、スキル表と参照を直す。

どれも最後に突き合わせを行い、github スキルに従ってコミットしてください。

philtzjp/skills 本体では、スキルを削除したりリネームしたりしないでください。古い版のコピーを持つリポジトリや、ホームに導入済みの環境で、スキルが見つからなくなります。役目を終えたスキルは、統合先を案内する内容に置き換えて残します。

These are the procedures for changing a repository-specific skill or a skill in the philtzjp/skills repository itself.

Adding: Create
```
.agents/skills/<skill-name>/SKILL.md
```
, and add
```
name
```
and
```
description
```
to the frontmatter. Describe specifically when the skill should be used. Create the symlink and add a row to the skill table.
Deleting: Delete the directory, symlink, and skill-table row. Search for and update references to the skill in other skills and AGENTS.md.
Renaming: Change the directory name and the frontmatter
```
name
```
, recreate the symlink, and update the skill table and references.

In every case, perform a final reconciliation and commit the changes by following the github skill.

Do not delete or rename skills in the philtzjp/skills repository itself. Doing so would make the skills unavailable in repositories that contain copies of older versions and in environments where they have already been installed in the home directory. Retain a skill whose purpose has been completed by replacing its content with guidance that directs users to its merge destination.