Skills 実践 — 設計と記述
いつ Skill 化するか・description・ワークフロー。
Skills 実践ガイド（2026）
Skill = 必要なときだけ読む手順。サンプル: pr-review · 置き場。
いつ Skill 化するか
| シグナル | 昇格先 | 例 |
|---|---|---|
| 毎日 1 ショットで済む | Command（.cursor/commands/） | /review · /verify |
| 週 2 回以上・多段チェックリスト | Skill | PR 前 lint+test+docs 整合 · デプロ手順 |
| 毎セッション必須の禁止・下限 | Rule（alwaysApply / globs） | git 安全 · ドメイン不変条件 |
| 同じミスが 2 回以上 | lessons → Rule 1 条 | tasks/lessons.md から .mdc へ |
| 広い調査・grep だけ | Task / Subagent（Skill にしない） | 別 AI への任せ方 |
Skills と Subagents（Task）の使い分け
flowchart TD
ask[依頼内容] --> repeat{同じ手順を
繰り返す?} repeat -->|はい| skill[Skill SKILL.md] repeat -->|いいえ| wide{広い調査
だけ?} wide -->|はい| task[Task explore 等] wide -->|いいえ| rule[Rules / Plan / docs] skill --> impl[メインが実装] task --> impl
繰り返す?} repeat -->|はい| skill[Skill SKILL.md] repeat -->|いいえ| wide{広い調査
だけ?} wide -->|はい| task[Task explore 等] wide -->|いいえ| rule[Rules / Plan / docs] skill --> impl[メインが実装] task --> impl
| 種類 | 役割 | 向く場面 | 向かない場面 |
|---|---|---|---|
| Skill | 再利用ワークフロー（チェックリスト・scripts） | PR レビュー · ADR 執筆 · デプロ | 「どこにある？」だけの grep |
| Subagent / Task | 別コンテキストで調査・実行（.claude/agents/ で定義） | パス一覧 · 複数 dir 探索 · セキュリティレビュー | 直前の実装の続きデバッグ |
| Rule | 毎回の下限 | 禁止 · 参照順 · globs 規約 | 10 ステップの手順全文 |
初めて Skill を 1 つ作る（手順）
- 対象を決める — 直近 2 週間で 2 回以上頼んだ多段手順（例: PR 前確認）
- ディレクトリ — チーム共有なら
.agents/skills/<name>/、Cursor のみなら.cursor/skills/<name>/（配置表） - SKILL.md — frontmatter の
name（フォルダ名一致）とdescription（命令形・ユースケース）を書く（フロントマター · テンプレ） - 本文 — チェックリスト + 出力形式。500 行超えたら
references/へ分割 - 任意 scripts/ — 非対話・
--help必須（Agent Skills 仕様） - AGENTS.md に 1 行 — 「PR 前: .agents/skills/pr-review/SKILL.md」
- 発火確認 — Agent に「PR 前のセルフレビューして」と依頼し Skill が読まれるか確認
- 既存資産から — Cursor なら
/create-skillまたは/migrate-to-skills（移行）
記述とトラブル回避
description の書き方と評価
description は Skill のトリガー。曖昧な 1 行は発火しない。
- 命令形 — 「〜の場合に使用してください」（agentskills.io 推奨）
- ユースケース列挙 — 「PR 前」「デプロ」「ADR ドラフト」など具体語
- 暗黙の依頼もカバー — 「レビュー準備」「提出前チェック」等の言い換え
評価ループ（目安）:
- should-trigger 10 件 · should-not-trigger 10 件のプロンプトを用意
- 各 3 回 Agent に依頼し、Skill が読まれたか確認
- 過少トリガー → description を広げる / 過剰トリガー → 絞る
副作用ありの Skill — 手動呼び出し専用にする
デプロや DB マイグレーションなど副作用があるワークフローは disable-model-invocation: true を付ける。description によるオート発火を防ぎ、/deploy のように明示的に呼び出した時だけ実行される。
---
name: deploy-staging
description: ステージング環境にデプロイする
disable-model-invocation: true
---
1. `make test` で全テスト確認
2. `vercel deploy` でプレビュー URL 取得
3. HEAD の 200 を curl で確認
よくある失敗
- 手順を Rule（
alwaysApply: true）に入れてトークン浪費 descriptionが「この Skill は〜します」だけ（トリガーにならない）- 副作用ある Skill に
disable-model-invocation: trueを付け忘れて意図せず発火 - 仕様全文を Skill に複製（正本は
docs/） - 調査だけの Task を Skill 化（grep 手順は
.claude/agents/Subagent 向き） nameとフォルダ名不一致（検出・読み込み失敗）