kzntov Skill Design Policy
手順
1. 近い既存スキルを確認する
- 近い個人スキルを読み、普段の長さ、粒度、構造、書き方を把握する。
- 既存スキルを更新する場合は、そのスキルを最初に読む。
- 既存の形をそのままコピーせず、今回必要な部分だけ参考にする。
2. テンプレートを使って案を作る
次の形を基本にし、不要な見出しは追加しない。
---
name: skill-name
description: 何を行い、どの依頼で使うか
---
# Skill Name
## 手順
### 1. 最初の作業
作業内容を書く。
- この段階だけに当てはまる注意点を書く。
### 2. 次の作業
作業内容を書く。
- この段階だけに当てはまる注意点を書く。
## 注意点
- すべての手順に共通する注意点だけを書く。
- 必要な場合だけ、スキルの対象外を書く。
手順は実際に作業する順番で並べる。注意点は該当する手順の直下に置き、どの手順にも共通するものだけ最後へ置く。
3. 案を確認してから作成または更新する
- テンプレートに当てはめた案をユーザーへ見せ、確認を待つ。
- 合意後に必要最小限の内容で作成または更新する。
references/、scripts/、assets/は、実際に必要なものだけ追加する。skill-creatorが利用できる場合は、雛形生成と検証に使う。
4. 形式を確認する
- frontmatter、名前、参照先、不要なプレースホルダーの残存を確認する。
SKILL.mdの行数を確認する。300行を超える場合は、分割案を示してユーザーの指示を待つ。
5. ブラッシュアップする
system-overview-documentationスキルを確認し、ドキュメントとして整理されているかを確認・修正する
最初は小さく作る
スキルは最初から完璧にしようとせず、実行に必要な最小内容で作る。 長いスキルはコンテキストを多く消費し、重要な指示を見つけにくくする。初回は実運用で何が不足するか分からないため、想像で説明や例外を増やすと、後から何を削るべきか判断しにくい。
まず短く作って実際に使い、迷いや失敗が起きた箇所だけを後から足す。短い初版は、修正、追加、削除の判断もしやすい。
注意点
- 複数の独立した目的を一つのスキルへ詰め込まない。
- AIが一般知識で判断できる内容、作成経緯、実行時に確認できる事実を書かない。
- 低性能なAIモデルで実行する前提で書く
- 実行手順が曖昧な指示は避ける。例えば「ファイルをパースし出力する」は良くなく、「ファイルを以下コマンドでパースし、xxxというファイル名でyyyに出力する」
- スクリプト化できるならスクリプトで行う
- 一方、低性能なAIモデルは長い指示を無視する。特に否定形「〜〜は禁止」は高い確率で無視する。そのため簡潔にしながら、曖昧な判断を求めないことが必要だ
- 例えば「必要な場合は〜〜」するは良くない。必要な場合を低性能モデルは判断できないためだ。この場合、「AAAという条件であれば〜〜〜」なら良い。判断基準を明快にすべきだ
- READMEや補助ファイルを、丁寧そうという理由だけで追加しない。