SkillsとRulesを運用するときのよくある課題

2026-04-01

17 days ago

開発環境

GitHub Copilot（.github/instructions / .github/skills を活用）

前提

GitHub Copilot を開発で活用する場合、以下のような構成が多いです。

.github/instructions：ルール・前提・設計思想
.github/skills：タスク別の実践ガイド（手順・判断ロジック）

しかし実際に運用していくと、次のような問題に陥りがちです。

instructions に実装手順やコード例を書いてしまう
skills が不足していて instructions に情報が集中する
同じ内容が instructions と skills に重複する

この記事では、この「よくある崩れ方」とその改善方法を整理します。

本題

よくある課題①：instructions に手順やコード例を書いてしまう

⚠️ 問題：例えばフォーム実装の instructions がこうなっているケース

## フォーム実装ルール

- useServerAction を使用すること

### 実装例

```tsx
const form = useForm(...)
```

この状態の問題は以下です。

ルールと手順が混在する
Copilot が「これは守るべきルールなのか、参考例なのか」を判断しづらい

🛠 改善：instructions はルールだけに絞る

## フォーム実装ルール

- フォームは useServerAction を利用すること
- バリデーションは Zod を使用すること

手順・コード例は skills に移動

## 手順

1. useForm を定義
2. Server Action を作成
3. form に action を紐付ける

skills/create-form/SKILL.md

```tsx
const form = useForm(...)
```

skills/create-form/references/form-patterns.md

👉 ポイント「何をすべきか」と「どうやるか」を分離する

よくある課題②：skills が不足している

⚠️ 問題：skills が少ない（あるいはない）と、結果的に instructions にすべて書くことに

よくある状態：

instructions/
  form.instructions.md ← 手順も全部ここ
  server-actions.instructions.md ← 手順も全部ここ

これだと、Copilot の精度が下がる印象があります。

🛠改善：タスク単位で skills を分割する

.github/skills/
├── create-form/
├── create-server-action/
├── create-component/

例：create-server-action

# SKILL.md

name: create-server-action
description: |
  Server Action を新規作成する手順

## 手順

1. "use server" を宣言
2. input をバリデーション
3. DB処理
4. エラーハンドリング

👉 ポイント「やりたいこと単位」で skills を切る

よくある課題③：instructions と skills の重複

⚠️ 問題：例えば以下のような状態

instructions に責務説明あり
skills にも同じ説明あり

# instructions
- Container はデータ取得を担当

# skills
- Container はデータ取得を担当（同じ内容）

これにより、方針変更時のドキュメント修正漏れが発生する可能性が高いです。

🛠 改善：単方向参照に統一する

ルール：

instructions = 唯一の正
skills = instructions を参照するだけ

- Container はデータ取得を担当

instructions/page-container-presentation.instructions.md

> ルールは instructions を参照

skills/architecture-guide/SKILL.md

👉 ポイント「同じことは1箇所にしか書かない」

判断基準（ここが一番重要）

迷ったときはこの表で判断すると整理しやすいです。

|      内容      |    書く場所        |
| ------------- | ---------------- |
| ルール・禁止事項 | instructions     |
| 実装手順       | skills           |
| コード例       | skills/references|
| 設計思想       | instructions     |
| 判断ロジック    | skills           |

最終的な理想構成

.github/
├── instructions/
│   ├── form.instructions.md
│   ├── server-actions.instructions.md
│   └── ...
│
└── skills/
    ├── create-form/
    │   ├── SKILL.md
    │   └── references/
    │
    ├── create-server-action/
    │   ├── SKILL.md
    │   └── references/

さいごに

Copilot を活用する上で一番重要なのは「情報の構造」です。

特に崩れやすいのはこの3つです。

instructions に手順を書いてしまう
skills が不足する
重複が発生する

改善の本質はシンプルで、

「ルール」と「手順」を分離すること

これを徹底するだけで、

Copilot の精度が上がる
ドキュメントの保守性が上がる

というメリットが得られます。