Claude Code Skills完全ガイド——カスタムスキルの書き方とベストプラクティス

はじめに

Claude Codeを使っていて、こんな経験はありませんか？

• 毎回同じようなコーディング規約を説明している
• プロジェクト固有のルールを何度も伝えている
• 「any禁止」「非nullアサーション禁止」を繰り返し指示している

Skills（スキル） を使えば、これらの問題を解決できます。

本記事では、実際のプロジェクトで使われているコーディング規約スキルを参考に、効果的なスキルの書き方を解説します。

スキルの読み込みフロー

Claude Codeがスキルをどのように読み込むか、Mermaid図で見てみましょう。

おすすめのディレクトリ構成

実際のプロジェクトで効果的に使われている構成です。

テキスト形式での構成:

.claude/skills/
└── coding-standards/
    ├── SKILL.md              # 概要とクイックリファレンス
    ├── templates/
    │   ├── coding-rules.md       # TypeScript規約
    │   ├── component-patterns.md # コンポーネント実装パターン
    │   └── page-creation.md      # ページ作成テンプレート
    └── examples/
        ├── component-example.md  # コンポーネント実装例
        └── store-example.md      # 状態管理実装例

SKILL.mdの実践例

全体構成

---
name: coding-standards
description: コーディング規約、アーキテクチャ、コンポーネント作成など、実装に必要な全てのガイド
---

# プロジェクト コーディングガイド

## 概要

このスキルは以下の内容を統合しています：
- TypeScriptコーディング規約
- アーキテクチャ・ディレクトリ構造
- コンポーネント実装パターン

## 必須: 実装前にテンプレートを確認

**BLOCKING: 実装を開始する前に、必ず該当するテンプレートを読み込むこと**

| 実装内容 | 確認するテンプレート |
|----------|---------------------|
| コンポーネント作成 | templates/component-patterns.md |
| ページ作成 | templates/page-creation.md |
| 状態管理 | templates/store-patterns.md |

## クイックリファレンス

### TypeScript規約
- **any禁止** - 具体的な型を使用
- **非nullアサーション禁止** - 適切なnullチェック
- **型アサーション（as）禁止** - Zodスキーマでバリデーション

### 命名規則
- ファイル名: kebab-case
- コンポーネント: PascalCase
- 変数・関数: camelCase

## 禁止事項

- useEffectでのデータ取得禁止
- page.tsxでの"use client"禁止
- console.logの残存禁止

ポイント

1. BLOCKINGキーワード — 「必ず読め」を強調
2. テーブルで整理 — 何をどこで確認するか明確に
3. クイックリファレンス — よく使うルールを簡潔に
4. 禁止事項 — やってはいけないことを明示

templates/の具体例

templates/coding-rules.md

TypeScript規約の詳細を記述します。

# TypeScriptコーディング規約

## 禁止事項

### 1. any型使用禁止

// 間違い
const data: any = fetchData()

// 正しい
const data: User[] = fetchData()

**ESLintルール**: typescript-eslint/no-explicit-any: error

### 2. 非nullアサーション禁止

// 間違い
const user = users.find(u => u.id === id)!

// 正しい
const user = users.find(u => u.id === id)
if (!user) {
  throw new Error("ユーザーが見つかりません")
}

**ESLintルール**: typescript-eslint/no-non-null-assertion: error

### 3. 型アサーション（as）使用禁止

// 間違い
const data = response as UserData

// 正しい（Zodでバリデーション）
const result = userDataSchema.safeParse(response)
if (!result.success) {
  throw new Error("バリデーションエラー")
}
const data = result.data

## 命名規則

### ファイル名
- kebab-case（例: user-list-view.tsx）
- viewsディレクトリ: -viewサフィックス必須

### コンポーネント名
- PascalCase（例: UserListView）
- ファイル名と対応すること

### 変数・関数名
- camelCase（例: fetchUsers, handleDelete）

## JSDocコメント必須

全ての関数には日本語でJSDocコメントを記述すること。

/**
 * ユーザー情報を取得する
 *
 * @param userId - ユーザーID
 * @returns ユーザー情報またはnull
 */
export const fetchUserById = async (userId: string) => {
  // 実装
}

templates/component-patterns.md

コンポーネント分割のルールを記述します。Propsの最小化原則をMermaid図で見てみましょう。

# コンポーネント分割ルール

## 重要: Propsの最小化原則

**できるだけPropsを減らし、ストアから直接データを取得する**

### 間違い: Propsでデータを渡す

// 親コンポーネント
<UserSection
  user={user}
  setUser={setUser}
  validationErrors={errors}
/>

// 子コンポーネント
const UserSection: FC<Props> = ({
  user,
  setUser,
  validationErrors
}) => {
  // ...
}

### 正しい: ストアから直接取得

// 親コンポーネント
<UserSection />

// 子コンポーネント
const UserSection: FC = () => {
  const { user, setUser, errors } = useUserStore()
  // ...
}

## 分割の判断基準

- 500行を超えたらコンポーネント分割を検討
- 機能単位で分割（フォームセクション、リスト表示など）
- 各コンポーネントが独立してストアからデータを取得

## ディレクトリ構造の一致

app/(protected)/とviews/の構造は一致させること

app/(protected)/customer/page.tsx
 ↕ 対応必須
views/customer/customer-view.tsx

examples/の具体例

examples/component-example.md

実際のコンポーネント実装例を記述します。

# コンポーネント実装例

## ユーザー編集フォーム

### 要件
- ユーザー情報の編集
- バリデーション付き
- 保存・キャンセル機能

### ファイル構成

views/user/
├── user-edit-view.tsx        # メインビュー
├── user-basic-section.tsx    # 基本情報セクション
└── user-address-section.tsx  # 住所セクション

### メインコンポーネント

const UserEditView: FC = () => {
  const { user, saveUser } = useUserStore()

  return (
    <div>
      <UserBasicSection />
      <UserAddressSection />
      <SaveButton onClick={saveUser} />
    </div>
  )
}

### セクションコンポーネント

// Propsなし、ストアから直接取得
const UserBasicSection: FC = () => {
  const { user, setUser, errors } = useUserStore()

  return (
    <section>
      <Input
        label="名前"
        value={user.name}
        onChange={(e) => setUser({ ...user, name: e.target.value })}
        error={errors.name}
      />
    </section>
  )
}

### ポイント
- Propsは最小限（メインビューのみ）
- 各セクションがストアから独立してデータ取得
- 500行以下に収める

スキル作成の手順

# 1. ディレクトリ作成
mkdir -p .claude/skills/coding-standards/templates
mkdir -p .claude/skills/coding-standards/examples

# 2. SKILL.md作成（概要のみ、50〜100行）
touch .claude/skills/coding-standards/SKILL.md

# 3. テンプレート作成（詳細ルール）
touch .claude/skills/coding-standards/templates/coding-rules.md
touch .claude/skills/coding-standards/templates/component-patterns.md

# 4. 実装例作成
touch .claude/skills/coding-standards/examples/component-example.md

ベストプラクティスまとめ

スキルの構成要素とその役割をMermaid図で整理します。

効果

このようなスキルを作成することで：

• 一貫性: チーム全体で同じルールを適用
• 効率: 毎回ルールを説明する必要がない
• 品質: コーディング規約違反を防止
• 学習: 新メンバーのオンボーディングに活用

繰り返し伝えているルールがあれば、スキル化を検討してみてください。プロジェクト全体の品質と効率が向上します。

---

参考リンク：

• Claude Code Skills 公式ドキュメント
• Skills ベストプラクティス