Claude Code スキルの作成で学んだ、大きなファイルとの向き合い方

問題の発覚：見逃したアフィリエイトリンク

Claude Code でカスタムスキルを作成していました。ドラフト記事から完成記事を自動生成する仕組みです。この日は哲学・心理学系の記事で、ストア哲学やACT（アクセプタンス&コミットメント・セラピー）について書いた内容を処理していました。

スキル（/draft-to-article）を実行すると、Claude Code は問題なく記事を生成してくれました。日本語版・英語版の両方が作成され、関連するアフィリエイトリンクも埋め込まれています。

「よし、できた」

そう思って記事を確認したときに気づきました。

「あれ、ストア哲学とACTの書籍リンク、入ってないな」

ドラフト内で明示的に言及している書籍なのに、スキルが見逃していたのです。正直ここで詰まりました。

私はClaude Codeに聞きました。
「moshimo-card-rJcAE と moshimo-card-YB58h これもショートコードに追加してほしかったんだけど見つけられてた？」

Claude Code はすぐに Grep で検索してくれました。

grep -i "(moshimo-card-rJcAE|moshimo-card-YB58h)" content/affiliates.yaml

「見つかりました！完璧に関連する書籍ですね」

Claude Code は見つけたアフィリエイトリンクの内容を確認し、記事の適切な箇所に追加してくれました：

moshimo-card-rJcAE: ストア派哲学入門（ストア哲学の説明の後）
moshimo-card-YB58h: よくわかるACT（ACTの説明の後）

記事は完成しました。しかし私は疑問に思いました。

「なぜ最初の実行で見つけられなかったんだろう？」

最初のつまずき：スキルが認識されない

その前に、実はもう一つ問題がありました。スキルを作成したのに Unknown skill: draft-to-article というエラーが出たのです。

「skills を作ったのですが Unknown skill: draft-to-article と出ます」

Claude Codeに相談すると、まずファイル構造を確認してくれました。

ls -la .claude/skills/
# -rw-r--r-- 1 user 197609 4324  1月 30 11:39 draft-to-article.md

私は .claude/skills/draft-to-article.md としてファイルを配置していました。しかしこれが間違いでした。

Claude Codeは claude-code-guide agentを起動して正しい形式を確認し、修正方法を教えてくれました。

正しい構造はこうです：

.claude/
└── skills/
    └── draft-to-article/
        └── SKILL.md

ポイントは3つ：

ファイル名は SKILL.md（大文字）
スキル名のディレクトリを作る
YAML frontmatter を含める

---
name: draft-to-article
description: ドラフト記事から日本語・英語記事を生成し、アフィリエイトを提案する
user-invocable: true
---

Claude Codeがディレクトリを作成し、正しい形式でファイルを配置してくれました。これでスキルが認識されました。

意外とここが肝です。ドキュメントには書いてあるのですが、実際に動かしてみないと気づかない構造でした。

アフィリエイト検索の失敗

スキルが動くようになり、記事生成を実行しました。

/draft-to-article

私が設計したスキルの処理フローはこうです：

graph TD
    A[ドラフト読み込み] --> B[カテゴリ・タグ決定]
    B --> C[アフィリエイト検索]
    C --> D[記事生成]
    D --> E[完成]

    C --> F{affiliates.yaml<br/>検索}
    F -->|一般キーワード| G[coach, counseling]
    F -->|固有名詞| H[ストア哲学, ACT]

    G --> I[Coachee<br/>見つかった]
    H --> J[書籍リンク<br/>見逃した]

    style J fill:#f9f,stroke:#333

スキルは affiliates.yaml から関連するアフィリエイトリンクを探すよう設計していました。このとき、Claude Codeは "coach" や "counseling" といった一般的なキーワードで検索を実行しました。

結果、Coachee（キャリアコーチングサービス）のリンクは見つかりました。

[📦 商品リンク: moshimo-coachee-banner-728x90]

しかし、ドラフト内で明示的に言及していた以下は見逃しました：

ストア派哲学入門（書籍）
よくわかるACT（書籍）

記事を確認して、私が気づいて指摘するまで、スキルはこれらを検出できなかったのです。

原因の分析：なぜ見逃したのか

私が設計したスキルなのに、なぜ見逃したのか。振り返ってみると、3つの問題がありました。

1. ファイルサイズの壁

affiliates.yaml は 416KB のファイルです。Claude Code の Read tool には 256KB の制限があります。

私が最初に書いたスキルでは、Read tool でファイル全体を読もうとしていました。しかし当然エラーになりました。そこでスキルの設計を変更し、「最初の 100 行だけ読む」という戦略にしました。

これが失敗でした。関連するアフィリエイトリンクはファイルの後半にあったのです。

2. 検索戦略の不足

スキルには "coach" や "counseling" といった一般的なキーワードで検索するよう指示していました。

しかしドラフト内容を見れば、こうした固有名詞が明示されていました：

ストア哲学
エピクテトス
マルクス・アウレリウス
ACT（アクセプタンス&コミットメント・セラピー）

これらの書籍がアフィリエイトリンクとして登録されていました：

[📦 商品リンク: moshimo-card-rJcAE]

[📦 商品リンク: moshimo-card-YB58h]

これらで検索するようスキルに指示すべきでした。

3. プロセスの順序問題

私が設計したスキルは、アフィリエイト検索を「カテゴリ・タグを決める前」に実行していました。つまり、ドラフト全体を深く読み込む前に、表面的なキーワードだけで検索していたのです。

ドラフトの最後のセクション「古くて新しい智慧」で詳しく言及されていたのに、そこまで丁寧に読むよう設計していませんでした。

改善：SKILL.md のブラッシュアップ

原因がわかったので、Claude Code に依頼しました。

「見つけられなかった原因って何だと思う？分析して SKILL.md をブラッシュアップしてください」

Claude Code は私の指示を受けて、スキルの問題点を分析し、改善案を提示してくれました。

改善前の検索手順

### アフィリエイト分析
- affiliates.yaml から関連リンクを検索
- 一般的なキーワードで検索

これだけでした。抽象的すぎて、実行時の判断基準が曖昧だったのです。

改善後の検索手順

Claude Code が提案してくれた改善版はこうです：

### アフィリエイト分析（重要）

**STEP 1: ドラフトから固有名詞・専門用語を抽出**
- 書籍タイトル、著者名、哲学・理論名
- サービス名、商品名、ブランド名
- 技術用語、フレームワーク名、ツール名
- 抽出した用語をリスト化

**STEP 2: affiliates.yaml を Grep で検索（必須）**
- affiliates.yaml は大きいため Read tool では全体を読み込めない
- 必ず Grep tool を使用して抽出した固有名詞で検索

**STEP 3: 複数の検索を並行実行**
- 抽出した固有名詞ごとに並列で Grep 検索
- 一般的なキーワードでも検索
- 見逃しを防ぐため、複数の検索パターンを試す

さらに、Claude Code は具体的なケーススタディも追加してくれました：

## アフィリエイト検索の実例

### ケーススタディ: 哲学・心理学系の記事

ドラフト内容から抽出すべき固有名詞:
- ストア哲学 / Stoic philosophy
- エピクテトス / Epictetus
- マルクス・アウレリウス / Marcus Aurelius
- ACT / アクセプタンス&コミットメント・セラピー
- コーチング / coaching

検索パターン（並行実行）:
- Grep pattern: "(ストア|stoic|エピクテトス|epictetus|マルクス)"
- Grep pattern: "(ACT|アクセプタンス|acceptance|コミットメント)"
- Grep pattern: "(coach|counseling|カウンセリング|コーチ)"

期待される結果:
- moshimo-card-xxxxx: ストア派哲学入門
- moshimo-card-yyyyy: よくわかるACT
- moshimo-coachee-banner: Coachee

「OKです。良くなったと思います」

私はClaude Codeの提案を承認しました。

検索戦略の比較

改善前後の検索戦略を図にするとこうなります：

graph LR
    subgraph 改善前
    A1[ドラフト読み込み] --> B1[一般キーワード抽出]
    B1 --> C1[Read tool<br/>最初の100行]
    C1 --> D1[検索実行]
    end

    subgraph 改善後
    A2[ドラフト読み込み] --> B2[固有名詞を全抽出]
    B2 --> C2[Grep tool<br/>全体検索]
    C2 --> D2[並行検索実行]
    D2 --> E2[日英両方で検索]
    end

    style D1 fill:#fcc,stroke:#333
    style E2 fill:#cfc,stroke:#333

重要なのは「Read ではなく Grep を使う」ということです。

大きなファイルを扱うとき、全部読み込もうとするとサイズ制限に引っかかります。しかし Grep tool なら、ファイル全体から効率的に検索できます。

学んだこと：大きなファイルとの向き合い方

この経験から、私は大きなファイルとの向き合い方について学びました。

1. ツールの使い分け

Claude Code のツールにはそれぞれ得意・不得意があります。

Read tool: 小さいファイル（< 256KB）を全体読み込み
Grep tool: 大きいファイルから特定パターンを検索
並行実行: 複数の検索パターンを同時に試す

最初は「Read で読めないなら、一部だけ読めばいい」と考えていました。しかしこれは間違いで、「Read で読めないなら、Grep で検索すればいい」が正解でした。

2. 固有名詞を見逃さない

一般的なキーワードだけでなく、固有名詞（書籍名、サービス名、技術用語）を丁寧に抽出することが重要です。

私はドラフトを読むとき、「コーチング」という一般的な言葉には注目していましたが、「ストア哲学」「エピクテトス」「ACT」といった具体的な固有名詞をスルーしていました。

ドラフトの全セクション、特に最後のセクションまで丁寧に読む必要があります。

3. チェックリストの重要性

Claude Code の提案を受けて、スキルに以下のチェックリストを追加しました：

ドラフト全文を読んだか（特に最後のセクション）
固有名詞を全て抽出したか
Grep tool を使って並行検索したか（Read は使わない）
日英両方のキーワードで検索したか
複数の検索パターンを試したか
検索結果から link-id を正しく抽出したか
記事内容に合った自然な配置場所を考えたか

チェックリストがあると、次回同じミスを防げます。自分で考えるだけでなく、Claude Code にチェック項目を提案してもらうことで、見落としていた観点に気づけました。

まとめ

Claude Code のカスタムスキル作成を通じて、私は「大きなファイルとの向き合い方」を学びました。

特に重要だったのは：

ツールの特性を理解する: Read は小さいファイル、Grep は大きいファイル
固有名詞を見逃さない: 一般キーワードだけでなく、具体的な名詞を抽出
プロセスを明文化する: チェックリストとケーススタディで再現性を確保

失敗したときに「なぜ失敗したのか」を Claude Code と一緒に分析し、スキルを改善する。このプロセスそのものが、エンジニアリングの本質だと改めて感じました。

Claude Code は単なるコード生成ツールではなく、思考のパートナーでもあります。「見つけられなかった原因って何だと思う？」と問いかけると、私が見落としていた観点を提示してくれる。

そうした対話を通じて、スキルは進化していきます。

Claude Code について詳しく学びたい方へ

Claude Code の実践的な使い方やベストプラクティスについては、以下の書籍が参考になります：

[📦 商品リンク: moshimo-book-3CCtM]

[📦 商品リンク: moshimo-book-fb94K]