私たちのチーム（VeriCerts株式会社）でも、開発効率化のためにClaude Codeの「Skills」を社内で共有し、日々試行錯誤を重ねています。
うまくいかないSkillがあれば個々人で調整しながらブラッシュアップを続けていますが、「そもそもどんなSkillを作るべきか？」「どう書けばClaudeがうまく動いてくれるのか？」といったベストプラクティスについては、まだ手探りな部分も多いのが実情です。
そんな中、AnthropicのエンジニアであるThariq氏が、X（旧Twitter）で「Claude CodeにおけるSkillsの使い方」について非常に有益な知見を共有していました。
元のポストはこちら:
Claude Codeの「Skills」は、AIエージェントの機能を拡張するための強力な仕組みですが、「単なるMarkdownファイル」と誤解されがちです。実際には、スクリプトやアセット、データを含むフォルダであり、エージェントが探索・操作できる柔軟な構造を持っています。
この記事では、Anthropic社内で数百のSkillsを運用して得られた「どのようなSkillを作るべきか」「良いSkillを書くための秘訣」をわかりやすくまとめました。
💡 1. どんなSkillを作るべきか？（9つのパターン）
Anthropic社内で活用されているSkillsは、大きく以下の9つのカテゴリに分類されるそうです。自社の組織に足りないものがないか、チェックしてみましょう。
① ライブラリ＆APIリファレンス
社内ライブラリや、Claudeが苦手とする一般的なライブラリの正しい使い方を教えるSkill。
例:
billing-lib（社内課金ライブラリのエッジケースや落とし穴）、frontend-design（デザインシステムをClaudeに学習させる）
② プロダクトの検証（Product Verification）
コードが正しく動くかをテスト・検証する方法を記述したSkill。Playwrightやtmuxなどの外部ツールと組み合わせて使われます。
例:
signup-flow-driver（ヘッドレスブラウザでサインアップからオンボーディングまでを実行し、各ステップで状態をアサートする）
③ データの取得と分析
データやモニタリングスタックに接続するSkill。認証情報やダッシュボードID、一般的なワークフローを含みます。
例:
funnel-query（サインアップ→アクティベーション→課金のファネルを見るためのクエリとテーブル情報）
④ ビジネスプロセス＆チームの自動化
反復的なワークフローを1つのコマンドで自動化するSkill。ログファイルに結果を保存することで、モデルが一貫性を保ちやすくなります。
例:
standup-post（チケットトラッカーやGitHubの活動を集約し、Slackにフォーマットされたスタンドアップを投稿する）
⑤ コードの足場作り（Scaffolding）＆テンプレート
特定の機能のためのボイラープレート（ひな形）を生成するSkill。コードだけでは表現しきれない自然言語の要件がある場合に特に有用です。
例:
new-migration（マイグレーションファイルのテンプレートとよくある落とし穴）
⑥ コード品質＆レビュー
組織内のコード品質を保ち、コードレビューを支援するSkill。
例:
adversarial-review（新鮮な目を持つサブエージェントを生成して批判させ、修正を実装し、指摘が些細なものになるまで反復する）
⑦ CI/CD & デプロイメント
コードベース内でのフェッチ、プッシュ、デプロイを支援するSkill。
例:
babysit-pr（PRを監視し、不安定なCIを再試行し、マージコンフリクトを解決し、自動マージを有効にする）
⑧ ランブック（障害対応手順）
Slackのスレッドやアラートなどの「症状」を受け取り、複数のツールを使って調査し、構造化されたレポートを作成するSkill。
例:
oncall-runner（アラートを取得し、よくある原因をチェックし、調査結果をフォーマットする）
⑨ インフラ運用
日常的なメンテナンスや運用手順を実行するSkill。破壊的なアクションを伴うものにはガードレールを設けます。
例:
<resource>-orphans（孤立したPodやボリュームを見つけ、Slackに投稿し、ユーザーの確認を得てからクリーンアップする）
🚀 2. 良いSkillを作るためのTips
作るべきSkillが決まったら、どのように書けばよいのでしょうか？ここでは、実践的なベストプラクティスを紹介します。
当たり前のことを書かない（Don't State the Obvious）
Claudeはすでにコーディングに関する多くの知識を持っています。知識に関するSkillを公開する場合は、Claudeの通常の思考パターンから外れるような情報に焦点を当てましょう。
（例：一般的なフォントやグラデーションを避けるよう指示するフロントエンドデザインのSkillなど）
「Gotchas（落とし穴）」セクションを作る
ファイルシステムと「段階的開示」を活用する
Skillは単なるMarkdownファイルではなく、フォルダです。ファイルシステム全体をコンテキストエンジニアリングの一環として捉えましょう。
- 詳細な関数シグネチャや使用例は
references/api.mdに分割する。 - 最終的な出力がMarkdownファイルの場合、
assets/にテンプレートファイルを置いてコピーさせる。
Claudeを縛りすぎない（Avoid Railroading Claude）
Claudeは指示に忠実に従おうとします。Skillは再利用性が高いため、指示を細かくしすぎないよう注意が必要です。必要な情報は与えつつ、状況に応じて適応できる柔軟性を持たせましょう。
セットアップを考慮する
ユーザーからのコンテキストが必要なSkill（例：Slackのどのチャンネルに投稿するか等）の場合、config.json に設定情報を保存するパターンが有効です。設定がない場合は、エージェントがユーザーに質問するようにします。
「Description」はモデルのためのもの
メモリとデータの保存
Skill内にデータを保存することで、記憶を持たせることができます。テキストのログファイルやJSON、あるいはSQLiteデータベースを使うことも可能です。
※Skillをアップグレードするとディレクトリ内のデータが削除される可能性があるため、${CLAUDE_PLUGIN_DATA} のような安定したフォルダに保存することが推奨されます。
スクリプトの保存とコード生成
Claudeにスクリプトやライブラリを与えると、ボイラープレートの再構築ではなく、「次に何をすべきか」という構成（Composition）にターンを費やすことができます。
オンデマンドのフック（On Demand Hooks）
Skillが呼び出されたときだけアクティブになり、セッション中のみ持続するフックを含めることができます。
-
例:
/careful（本番環境を触る時だけ、rm -rfやDROP TABLEなどの危険なコマンドをブロックする）
🤝 3. Skillの共有と管理（Distributing Skills）
作成したSkillはチームで共有することで真価を発揮します。
-
リポジトリにチェックインする（
./.claude/skills配下） - プラグイン化してマーケットプレイスで配布する
小規模なチームであればリポジトリへのチェックインで十分ですが、規模が大きくなると、内部のプラグインマーケットプレイスを使ってチームがインストールするSkillを選べるようにするのが効果的です。
マーケットプレイスの管理
Anthropicでは、中央集権的なチームが決定するのではなく、有機的に有用なSkillを見つけるアプローチをとっています。
- GitHubのサンドボックスフォルダにアップロードし、Slack等で試してもらう。
- トラクションが得られたら（Skill所有者の判断）、PRを出してマーケットプレイスに移動する。
※無駄なSkillや質の低いSkillが乱立するのを防ぐため、リリース前に何らかのキュレーション（審査）を行うことが重要です。
🎯 まとめ
SkillsはAIエージェントにとって非常に強力で柔軟なツールですが、まだ発展途上の分野です。
Thariq氏は、「これを決定版のガイドというより、うまくいったヒントの寄せ集めと考えてほしい」と述べています。Skillを理解する最良の方法は、まずは始めてみて、実験し、何が機能するかを確認することです。
最初は数行のコードと1つの「落とし穴（Gotcha）」から始まり、Claudeが新しいエッジケースにぶつかるたびに追記していくことで、強力なSkillへと成長していきます。
ぜひ、皆さんのチームでもClaude CodeのSkillsを活用して、開発体験を向上させてみてください！
参考リンク
- Thariq氏の元のXポスト
- Claude Code Skill Creator (※記事内で言及されていたツール)
VeriCerts株式会社は、Blockchain、IPFS、DID/VC、生成AIなどを活用し、Web3時代の信頼を支える技術を開発しています！技術情報を中心に投稿します！
Discussion