良いスキルの書き方

約5分

実際にスキルを書こうとしている方、書いたスキルが期待どおりに使われない方

スキルは書いただけでは機能しません。必要な場面で読み込まれ、迷いなく実行できる形になって初めて役に立ちます。

粒度は「1つの目的」で切る

大きすぎるスキルは、使わない手順まで読み込ませることになります。細かすぎるスキルは、数が増えて選択を難しくします。

目安は、人に「この作業をお願いします」と言える単位です。

スキルが使われない原因のほとんどは、手順の中身ではなく冒頭の説明にあります。何をするものかに加えて、どんなときに使い、どんなときに使わないかを最初に書きます。

docs 記事（src/content/docs/）を新規作成するときに使う。
既存記事の修正や、ブログ記事の作成には使わない。

「適切に」「必要に応じて」といった表現は、読み手によって解釈が変わります。具体的な条件に置き換えます。

# 判断できない
必要に応じてリンクを追加する

# 判断できる
同じセクション内の関連ページへのリンクを、本文末尾に2〜4件追加する

どこまでやれば終わりかを書かないと、途中で止まるか、頼んでいない範囲まで手を広げます。

## 完了条件
- 日本語版と英語版の両方が作成されている
- フロントマターの必須項目がすべて埋まっている
- 内部リンクがすべて既存ページを指している

スキルに書くのは判断と手順です。決まった処理はツールとして実装するほうが、速く確実になります。スキルの中で長いコマンド列を説明しているなら、ツール化の候補です。