AGENTS.md@.agents/skills · git:20261113.a912aab · 2026-11-13 · sha256 d00bbe31a6746207

AGENTS.md@.agents/skills git:20261113.a912aabA

Immutable. This exact content never changes and is served at /api/v1/blob/d00bbe31a6746207.

# スキルの書き方

スキルを書く人向けの決まり。スキルを使う人向けの案内はリポジトリ直下の AGENTS.md にある。

## 置き場所

1 スキル 1 ディレクトリ。名前は TODO.md の名前と同じにする。

```
<skill>/
  SKILL.md       手順。frontmatter に name と description
  references/    手順の中で必要になったときに読む資料
  assets/        出力のひな形など
  scripts/       (必要になったら) 手順で使うスクリプトとそのテスト
```

## 執筆と実装の規約

- SKILL.md の frontmatter の description の書き方 (いつ発火させたいかを書く)
- SKILL.md の冒頭に置く reference の表 (reference / 読むとき / 中身)
- 事実の置き場所: サービスやライブラリごとの事実は `references/` に 1 対象 1 ファイルで置き、SKILL.md には一般的な手順だけを書く
- データ源の reference (`references/sources/`) は、メタ情報の表に「確かめた日」「提供者」「配布ページ」「利用規約・ライセンス」の行を置く。比べるときに項目ごとに並べられるようにするためで、`scripts/check.py` が欠けと空を検査する
- スキルに入れるスクリプトは `scripts/` に置き、同じ場所に `test_*.py` を置く。標準ライブラリだけで動くようにし、GitHub Actions がスキルごとにテストを回す
- 足すのは、エージェントが自力で知りえないこと (環境、権限、規約、本人の判断、過去の失敗) と、評価で実際に失敗した場面への手当てだけにする。人間によいとされる手順を細かく決めると、記録に時間を使わせ、大きな手を選ばせなくすることがある (geo-software-swarm の unattended-runs)。足した規則は、evals で足す前と比べる
- 普段の言葉を使う。エージェントが作った独自の言い換えは、人間が読む負担になる (他のプロジェクトで、deploy を「配る」、endpoint を「口」と言い換えた箇所が 1,000 を超え、人間の負担になった例がある)
- 事実は確かめてから書く: 価格、無料枠、規約、対応機能は公式ページで確かめ、確かめた日と版を書く。確かめていないことは「未確認」と書く
- ライセンス上の注意: GPL / LGPL / AGPL などのコピーレフト、OSI 非承認、UNLICENSED、データの ODbL などの継承条件があるものは、組み込み、改変、配布、SaaS 提供のそれぞれで何が求められるかを書く
- 公開リポジトリに書かないもの: 社内の数値、取引先との契約条件、非公開の価格
- 文体: 日本語、em ダッシュを使わない、段落内で改行しない
- スキルを足す、消す、名前を変えたら TODO.md を直す。カードのようにデータを多数置くディレクトリは、TODO.md に `assets/services/`、`assets/apps/` のように末尾を `/` にして 1 行で書く (その下のファイルをまとめて数える)
- 利害関係の開示: 作者と関係のある製品を比べるスキルでは、SKILL.md の「注意」に 1 行だけ置き、文面はリポジトリ直下の AGENTS.md と揃える。スキルは単独でも入れられるので SKILL.md からは消さないが、同じスキルの reference には重ねて書かない (provider の reference の「執筆上の注意」は書き方の決まりなので別)