# Skill Design Policy

> Codexスキルを新規作成・更新する前に、責務、粒度、記載範囲、分割要否を決める。ユーザーが「スキルを作って」「この手順をスキル化したい」「既存スキルを見直したい」と依頼したときに使い、AIの提案とユーザーが求めるスキル像のずれを防ぐ。

- Skill: `kzntov/skill-design-policy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kzntov/skill-design-policy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kzntov/skill-design-policy/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: kzntov (https://skillmd.com/u/kzntov)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kzntov/skill-design-policy

---


# Skill Design Policy

## 手順

### 1. 近い既存スキルを確認する

- 近い個人スキルを読み、普段の長さ、粒度、構造、書き方を把握する。
- 既存スキルを更新する場合は、そのスキルを最初に読む。
- 既存の形をそのままコピーせず、今回必要な部分だけ参考にする。

### 2. テンプレートを使って案を作る

次の形を基本にし、不要な見出しは追加しない。

```markdown
---
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や補助ファイルを、丁寧そうという理由だけで追加しない。