> ## Documentation Index
> Fetch the complete documentation index at: https://agentskills.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# スキル作成のベストプラクティス

> 適切な粒度と十分な具体性を持つ Agent Skill を書くための実践指針。

## 実際の知見から始める

一般知識だけでスキルを書くと、抽象的で汎用的すぎる手順になりがちです。価値が出るのは、実案件で効いた API パターン、落とし穴、プロジェクト固有の慣習を取り込んだ時です。

有効な作り方は主に 2 つあります。

### 実タスクから抽出する

実際の作業をエージェントと進め、その途中で与えた修正や判断基準をスキルへ落とし込みます。

* うまくいった手順
* 修正したポイント
* 入出力の形式
* プロジェクト固有の前提

### 既存資産から合成する

runbook、社内ドキュメント、設定ファイル、レビューコメント、障害対応記録などを材料にしてスキル化します。重要なのは一般論ではなく、あなたの環境固有の情報です。

## 実行しながら磨く

初稿のスキルは、ほぼ確実に調整が必要です。実タスクで回し、成功例も失敗例も含めて見直します。

<Tip>
  最終出力だけでなく、実行トレースも見てください。無駄な試行が多いなら、手順が曖昧か、選択肢が多すぎる可能性があります。
</Tip>

## コンテキストを節約する

`SKILL.md` に載せるべきなのは、エージェントが素の状態では知らない情報です。

* プロジェクト固有の規約
* ドメイン固有の手順
* 非自明なエッジケース
* 使うべきツールや API の明示

不要なのは、一般的な背景説明です。

### 一貫した単位で切る

スキルの粒度は関数設計に近いです。狭すぎると複数スキルを同時に読む必要が出て、広すぎると発火精度が落ちます。

### 大きい内容は分割する

毎回不要な詳細情報は `references/` に逃がし、**いつそのファイルを読むか**を本文で指定します。

```markdown theme={null}
Read `references/api-errors.md` if the API returns a non-200 status code.
```

## 制御の強さを調整する

複数の進め方が許容される部分では自由度を持たせ、順番やコマンドが重要な箇所だけ厳密にします。

### メニューではなくデフォルトを示す

複数案を横並びで出すより、まず標準手段を 1 つ示し、例外時だけ代替案を書く方が安定します。

### 宣言より手順を書く

特定ケースの答えそのものより、どう考えて進めるかの手順を書く方が再利用性があります。

## 効果的なパターン

### Gotchas

Agent が自然には気づけない落とし穴を置きます。

```markdown theme={null}
## Gotchas

- `users` テーブルは soft delete を使うので `deleted_at IS NULL` が必要
- 認証系の `uid` と課金系の `accountId` は同じ値を指す
```

### 出力テンプレート

出力形式が重要なら、文章で説明するよりテンプレートを提示します。

### チェックリストと検証ループ

多段ワークフローでは、進捗チェックと再検証の手順を明示すると安定します。

## 次のステップ

* [description の最適化](/jp/skill-creation/optimizing-descriptions)
* [出力品質の評価](/jp/skill-creation/evaluating-skills)
* [scripts の使い方](/jp/skill-creation/using-scripts)