# 核心原則

## 目次

- 洗練 (Refine)
- 簡潔性 (Concise)
- SSoT 厳守
- 段階的開示・自由度
- スキルの種類
- 構造とフロントマター
- コード vs プロンプトの判断
- コンテンツガイドライン

---

## 洗練 (Refine)

スキルは**公式ドキュメントや安定した仕様**に基づいて書く。

| 良い | 避ける |
|------|--------|
| 公式APIスキーマ | 現在の実装コード |
| 安定した仕様 | 変更されうるパターン |
| 普遍的な原則 | プロジェクト固有のワークフロー |

**例外**: プロジェクト固有スキルは意図的に依存してよい（→ スキルの種類）

---

## 簡潔性 (Concise)

コンテキストウィンドウは共有資源。**本当に必要な情報だけ**を含める。

- 冗長な説明より簡潔な例
- 「このトークンコストに見合う価値があるか？」「Claudeが既に知っていないか？」を問う

---

## SSoT 厳守

**参照先の情報をスキル内に書かない。** 情報は必ず1箇所だけに存在させ、他の箇所からは参照する。スキーマが変更された時、スキル内のコピーは古くなり、矛盾が生じる。

違反パターンの具体例・監査手順 → [ssot-audit.md](ssot-audit.md)

---

## 段階的開示・自由度

詳細 → [patterns.md](patterns.md)（3段階ローディング、自由度パターン）

---

## スキルの種類

### 汎用スキル

どのプロジェクトでも使える。公式ドキュメント・仕様に基づく。

**原則**: プロジェクト固有の実装パターンに依存しない

### プロジェクト固有スキル

特定プロジェクトのワークフロー・データ構造に依存。

**原則**: 依存先を「依存」セクションで明示し、変更時の影響範囲を把握できるようにする

---

## 構造とフロントマター

### ディレクトリ構造

```
skill-name/
├── SKILL.md (必須)
├── scripts/ (任意)
│   └── *.ts / *.sh
└── references/ (任意)
    └── *.md
```

### フロントマター

```yaml
---
name: kebab-case（64文字以内、小文字・数字・ハイフンのみ）
description: 三人称で記述。何をするか＋トリガーフレーズ3つ以上（1024文字以内）
---
```

descriptionの書き方・良い例・悪い例 → [exemplar.md](exemplar.md)（descriptionの書き方）

---

## コード vs プロンプトの判断

スキルの処理を **scripts/ のコード** で実装するか、**SKILL.md のプロンプト指示** に任せるか。

| コードを書く（scripts/） | プロンプトで指示する（SKILL.md） |
|--------------------------|--------------------------------|
| 決定的（毎回同じ結果が必要） | 創造的・文脈依存 |
| ファイルシステム操作（再帰削除、ツリー構築） | コンテンツ生成・判断 |
| 外部ツール連携（git, gh, surge） | コードレビュー・分析 |
| 状態管理（フラグファイル、タイムスタンプ） | 対話的ワークフロー |
| スキーマに基づくファイル生成 | 自然言語の出力 |

### コード作成時の規約

- **TypeScript**: Bun で実行。`pnpm` スクリプト経由で呼び出す（直接実行禁止）
- **Bash**: 標準Unixツールのみ。`bash path/to/script.sh` で実行
- SKILL.md にはスクリプトの**目的・実行方法・出力**を記載（実装詳細は書かない）

スクリプト品質の原則と具体例 → [exemplar.md](exemplar.md)（スクリプトの品質）

---

## コンテンツガイドライン

禁止事項・サイズ目安 → [patterns.md](patterns.md)（アンチパターン、サイズ目安）