Claude Code の Agent Skill を自作する（本の表紙つき本棚と、記事の下書き保存を例に）

この記事でできること

Claude Code の Agent Skill を自分で作り、決まった手順を1つの依頼で実行できるようにします。例として、私が Obsidian の読書ログと Qiita の記事づくりで使っているスキルを2つ紹介します。

1. add-book：本のタイトルから ISBN と表紙画像の URL を調べ、Obsidian のノートに入れて、表紙つきの本棚に並べるスキル
2. qiita-write：既存の2つのスキル（qiita-draft と yomiyasu）を組み合わせて、記事を「書く → 推敲 → 下書き保存」まで1回で行うスキル

Claude Code は使ったことがあるが、スキルを自作したことはない人に向けて書いています。Obsidian は題材なので、使っていなくても読めます。

前提と環境

2026年10月時点の環境です。

項目	内容
OS	macOS
Claude Code	CLI 版
スクリプト	Python 3（標準ライブラリだけ）
Obsidian	Bases（.base ファイル）を使います

Agent Skill とは

Agent Skill は、Claude に特定の作業のやり方を教えるための、フォルダ単位の手順書です。Claude Code はプロジェクトの .claude/skills/<スキル名>/ にある SKILL.md を読み込みます¹。

私のスキルのフォルダは次の形です。

.claude/skills/
├── add-book/
│   ├── SKILL.md
│   └── scripts/
│       └── book_lookup.py
└── qiita-write/
    ├── SKILL.md
    └── scripts/
        └── outbound_check.py

SKILL.md の先頭に、name と description を書く frontmatter を置きます。description には、スキルが何をするかと、どんな依頼のときに使うかを書きます。Claude は依頼の内容と description を照らし合わせて、スキルを使うかどうかを決めます。description に実際の依頼の言い回しを入れておくと、呼び出されやすくなります。

scripts/ に、手順の中で呼ぶスクリプトを置けます。API の呼び出しや検査のような、毎回同じ結果になってほしい処理はスクリプトにし、SKILL.md にはそれを呼ぶタイミングと、結果の見方を書きます。

例1：本の表紙つき本棚を作る add-book

作りたかったもの

Obsidian には、ノートの frontmatter を表にしたりカードにしたりできる Bases という機能があります²。カード表示では、画像のプロパティを指定すると、その画像をカードの表紙にできます。

これを使って、読書ログを表紙つきの本棚にしようと考えました。本を追加するたびに、ISBN を調べて、表紙の画像 URL を探して、ノートに書き込む必要があります。この手間をスキルにまとめました。

本棚の定義

本のノートの frontmatter は次のとおりです。

---
type: book
title: 書名
author: 著者
isbn: "9780000000000"
cover: https://example.com/cover.jpg
status: to-read
tags: [resource/book]
---

isbn は数字だけの文字列なので、引用符で囲んで文字列として書きます。

本棚の .base ファイルは次のとおりです。image: note.cover で、cover プロパティを表紙画像に指定しています。

filters:
  and:
    - type == "book"
views:
  - type: cards
    name: 本棚
    order:
      - title
      - author
    image: note.cover
    imageFit: contain
    imageAspectRatio: 1.45
    cardSize: 160

調べる処理をスクリプトにする

ISBN の検索と表紙の取得は、scripts/book_lookup.py にしました。

• ISBN の検索：国立国会図書館サーチの OpenSearch API³ に書名と著者を渡し、ISBN の候補を一覧にします
• 表紙の取得：Amazon の書影の URL と、openBD⁴ の表紙 URL を順に試し、実際に画像が返ったものを採用します

表紙の取得で気をつけた点が1つあります。Amazon の書影の URL は、画像がない本でもエラーにならず、極小の透明な GIF を返します。そのため、HTTP のステータスだけでは「表紙がある」と判断できません。content-type が image/ で始まり、かつ本体が一定のバイト数以上であることを確かめるようにしました。

MIN_IMAGE_BYTES = 2000  # Amazon は書影がないと 43 バイトの透明 GIF を返す

def is_image(url):
    try:
        ctype, data = get(url)
    except Exception:
        return False
    return ctype.startswith("image/") and len(data) >= MIN_IMAGE_BYTES

使い方は次のとおりです。

python3 .claude/skills/add-book/scripts/book_lookup.py search "書名" "著者"
python3 .claude/skills/add-book/scripts/book_lookup.py cover 9780000000000

search は ISBN、書名、出版社、刊行年をタブ区切りで出力します。cover は表紙画像の URL を1行で出力し、見つからなければ NOT_FOUND と出力します。

SKILL.md に書いたこと

スクリプトで決まる部分は任せ、判断が要る部分を SKILL.md に書きました。

• 重複の確認：同じ本のノートがすでにあれば、新規には作らず、空の isbn と cover だけを埋める
• 版の選び方：ユーザーが版を指定していればそれを使い、なければ最初に刊行された単行本を選ぶ。コミック版や図解版は、頼まれない限り選ばない。迷ったら候補を示して聞く
• 表紙の目視確認：返ってきた URL の画像を保存して見て、書名が合っているかを確かめる。別の本の表紙やプレースホルダーを入れないため
• 表紙がないとき：cover は空欄にして、そのことを伝える。推測した URL は入れない

最後の2つは、スクリプトだけでは防げない失敗への対策です。ISBN が合っていても、サイトが別の本の画像を返すことはあります。そこで、画像を実際に見る手順を入れました。

description

add-book の description は次のように書いています。

description: 本を Obsidian の読書ログ（03_Resources/Books/）に追加し、ISBN と表紙画像URLを調べて frontmatter に入れ、Books.base の「本棚」カード表示に表紙付きで並べる。「本を追加して」「〜を読書ログに入れて」「表紙を付けて」「本棚に表紙が出ない」と頼まれたときに使う。既存の本ノートに isbn / cover を後から埋めるときにも使う。

前半でスキルがすること、後半でどんな依頼のときに使うかを書いています。「表紙が出ない」のような、困ったときの言い回しも入れておくと、そのときにも反応します。

例2：既存のスキルを組み合わせる qiita-write

作りたかったもの

Qiita の記事を書くときに、次の作業を毎回別々に頼んでいました。

1. 記事の構成を決めて書く
2. 外に出せない情報が入っていないか確かめる
3. AI が書いた日本語の不自然さを直す
4. Qiita CLI の形式で、下書きとして保存する

すでに公開されている2つのスキルがありました。

スキル	できること	ライセンス
qiita-draft5	Qiita CLI を前提にした記事の構成、記法、投稿前チェック、投稿の手順	MIT
yomiyasu6	AI が生成した日本語の比喩、曖昧な主語、過剰な太字などの推敲	MIT

この2つを自分で書き直さず、手順の順番と受け渡しだけを決めるスキルを作りました。それが qiita-write です。

手順を並べる

qiita-write の SKILL.md は、固定の値の表と7つの手順でできています。

手順	内容
1	聞き取り。テーマ、読者、題材、ファイル名の案を1回にまとめて聞く
2	材料集め。題材のノートを読み、外に出せない情報を一般化する
3	下書き。qiita-draft の資料を読んで構成を選び、原稿を書く
4	外向けのチェックと見直し。スクリプトと qiita-draft のチェックリストで確かめる
5	推敲。yomiyasu で推敲する
6	保存と照合。public/ に保存し、推敲後の内容と合っているかを確かめる
7	報告

最初に「固定の値」の表を置き、パスやコマンドを1か所にまとめています。手順の中ではその名前（ROOT、QIITA、YOMI など）で参照します。フォルダを移したときに直す箇所が減ります。

使ったしくみ

他のスキルの資料を読ませる

qiita-write は、qiita-draft の references/ にある構成パターン、記法、チェックリストを読むよう、手順の中で指示しています。スキルの中身をコピーせずにパスで指すので、元のスキルを更新すれば、qiita-write も新しい内容を使います。

外に出せない語を、スクリプトで拾う

手順4で scripts/outbound_check.py を使い、原稿を検査します。金額、大学名、IP アドレス、メールアドレスなどの正規表現と、仕事や家族に関わる固有名のリストに当てはまる語を一覧にします。当たりがあるときの終了コードは 1 です。

見落としを減らすための検査で、残すかどうかの最終判断は人が文脈で行います。そのため、スクリプトは「候補」を出すだけにしました。

保存後の改変を検出する

推敲のあとに本文を手で直すと、推敲の検査で確かめた内容と、保存した内容がずれてしまいます。yomiyasu には、検査した最終稿のハッシュを記録し、あとで verify で照合する機能があります。qiita-write では、保存の直後に verify を実行し、「ハッシュが記録と合いました」と出ることを確認する手順にしました。

下書きのまま止める

qiita-write は投稿（publish）をしません。frontmatter に ignorePublish: true を入れて保存するところまでで終わります。ignorePublish: true の記事は、publish --all の対象から外れます。ファイル名を指定すれば投稿できてしまうので、qiita-write の手順に publish は入れていません。保存したあとに grep で ignorePublish: true が入っていることを確認する手順も入れています。

投稿は別の依頼にして、1本ずつ内容を見てから行います。記事の公開は取り消しにくいので、自動の流れには入れませんでした。

名前を出さないと動かないスキルを呼ぶ

yomiyasu は、利用者が名前を出して頼んだときにだけ動くスキルです。qiita-write の途中から呼ぶために、プロジェクトの CLAUDE.md に「Qiita の記事を書くときは yomiyasu を使う」と書いておきます。yomiyasu は、CLAUDE.md で使うよう求められているときも、名前を出して頼まれたものとして扱います。

動かしてみてわかったこと

• スクリプトに任せる範囲を決めると、SKILL.md が短くなります。add-book は、検索と画像の判定をスクリプトにしたことで、SKILL.md に書くのは判断の基準だけになりました。
• スクリプトで防げない失敗は、SKILL.md に手順として書きます。表紙の目視確認がその例です。
• 他のスキルを組み合わせるときは、中身をコピーせず、パスで読ませます。元のスキルが更新されても、手元の手順書を直さずに済みます。
• 取り消しにくい操作（投稿、削除など）は、スキルの流れに入れず、別の依頼にします。

まとめ

Agent Skill は、SKILL.md に手順と判断の基準を書き、決まった処理はスクリプトに任せる形で作れます。今回は調べ物の自動化（add-book）と、既存スキルをつなぐ手順の自動化（qiita-write）の2つを紹介しました。

qiita-draft と yomiyasu は、どちらも MIT ライセンスで公開されているスキルです。

参考

1. Claude Code のスキルのドキュメント ↩

2. Obsidian Help: Bases ↩

3. 国立国会図書館サーチ API 仕様 ↩

4. openBD ↩

5. eruto-skills/qiita-draft ↩

6. nanaism/yomiyasu ↩