こんにちは、セイロップの藤田です。
現在弊社ではClaude CodeのTeamアカウントが希望者全員に配布されています。またグループ会社合同でのAIハッカソンが行われるなど、フルリモートながら社内でのAI熱の高まりを感じています。
というわけで、というわけでもないのですが、今回は以前作成した、Flutter開発に役立つClaude Codeで使えるエージェントスキルをこの場をお借りして紹介いたします。
どんなSkill？
Claude Codeのようなコーディングエージェントが、Dart/FlutterパッケージのAPIドキュメントに簡単にアクセスできるようにするスキルです。例えば、使いたいパッケージについて直接チャットで質問したり、最新のドキュメントに従って実装させたい時などに役立ちます。
似たようなツールにContext7などがありますが、今回は、そのDart/Flutter特化版という位置付けで作成しました。ならそれで良いじゃん、と言われた時のために用意したセールスポイントは次の通りです：
- ローカルで完結する
- オンラインのHTMLドキュメントをパースするのではなく、パッケージソースコードのキャッシュからドキュメントを生成します。AIのコンテキストに何が入るか把握できるという意味で透明性がありますし、何より無料です！
- AIが正確なバージョンのドキュメントを参照することを保証する
- 例えばプロジェクトがriverpodパッケージの2系を使っている場合は2系のドキュメント、3系を使っている場合は3系のドキュメントをエージェントに渡します。スクリプトで適切なバージョンを判定するため、AIに余計な推論をさせません。
- ドキュメントが小さい
- HTMLではなくマークダウン形式で、尚且つ装飾的な要素を可能な限り削っているため、トークン効率が良いです。例えばgo_routerパッケージの場合、
dart docコマンドで生成したHTMLのAPIドキュメントをmarkitdownでマークダウン化した場合と比べると文字数が約半分になります。
- HTMLではなくマークダウン形式で、尚且つ装飾的な要素を可能な限り削っているため、トークン効率が良いです。例えばgo_routerパッケージの場合、
スキルはnpx skillsやClaude Codeマーケットプレイスからインストールできます。よかったら使ってみてください。
大変だったこと
今回作成したスキルには内部でコマンドやスクリプトを実行する指示が含まれています。自然言語の指示だけで構成されたシンプルなSKILL.mdと比べると少し複雑になるわけですが、その中でも実装する上で特に大変だと感じたことがいくつかありました。
再現性が無い
同じSkill.md、同じAIモデル、同じプロンプトでも、SKILL.mdの指示に従ってくれる時とそうで無い時がありました。しかも、通常のプログラムと異なり、想定通り動かないからといってエラーになるわけでも無いため、なぜそうなったのか理由が分からないことが多かったです。
特に条件分岐のある指示で顕著でした。もしエラーならXXX、というようなケースです。初めはトラブルシューティングの項目を作り、上手くいかない時はそこを参照するよう指示していたのですが悉く無視されてしまいました。
またClaudeの賢さが裏目に出て、何かあってもClaude自身で解決方法を捻り出し結果の辻褄を合わせるようなケースもありました。最終的なアウトプットとしては正しいのですが、指示とは違う非効率的な方法なため、まあ良いかとはいきません。
非決定論的に柔軟な判断ができることはAIの強みですが、それが逆に仇となるケースもあります。スキルの実装コストは上がりますが、やはり決まりきった手順はスクリプト側に寄せて、AIに判断させないようにする方が挙動のブレを抑えられるようです。今回の場合、依存ツールの存在チェック、SDKパスの取得、コマンド実行など可能な限り手順をスクリプト化し、問題が起きた場合は次の指示をエラーメッセージとしてエージェントに返すことで動作を安定させることができました。
Anthropicが公開しているガイドラインには、スキルの性能評価に関して「感覚的な基準をある程度受け入れる必要がある」というようなことが書かれています。始めから100%の動作保証を目指すより、運用しながら都度微調整を繰り返していくというのが現時点での健全なスキル開発方法のようですね。プログラムのようにきっちり動くことを目標にするのは精神衛生上良くありません。
誰でもどこでも使える…？
同じスキルを全てのAIツールで使えるのが理想ですよね。実際、スキルの標準仕様と呼べるものがagentskills.ioに公開されています。しかし日進月歩な分野というのもあり、現状ツールごとにSKILL.mdの解釈が微妙に違ったり、ツール固有の機能が多くあったり、そもそも同じスキルでもAIモデルごとに挙動が違うなど、どのツールでもきちんと動くスキルを構築するのは中々大変だなと感じました。
例えば、Claude CodeのSkill.mdには変数を埋め込んだりコマンドの実行結果を埋め込んだりできます。これらはClaudeがスキルファイルを読み込む前に実際の値と置き換えられるため、文脈に合わせてSkill.mdの指示文を微調整することができます。
// 以下がプルリクエストの差分に置き換わる
!`gh pr diff`とても便利なのですが、Claude Code固有の機能なので、当然Codexのような他のエージェントが見るのは展開後の値ではなく元の変数名やコマンド実行文になります。すると、Claude Codeでは動くけれど他では動かないスキルになってしまいます。
そのため出来れば使用を避けたいところですが、私のスキルでは$CLAUDE_SKILL_DIRという変数がどうしても必要でした。これはSkill.mdのあるディレクトリの場所を表す変数で、Claude Codeがスキルファイルを読む前に絶対パスと置き換えてくれます。スキルと一緒に使用するスクリプトの場所を、Skill.md内で絶対パスとして指定したい時などに使えます。
…というのはスキルを作成していた2026年3月ごろの話でした。改めて確認したところ記事公開時点では修正されており、
$CLAUDE_SKILL_DIRなしでも問題なく動いています。
相対パスで指定すれば変数使わなくても良いよね、という話ではありますし、実際agentskills.ioにも「Skill.mdで他のファイルを参照する場合はスキルディレクトリからの相対パスを使用する」と書かれています。しかし、スキルの開発中や運用中にClaude Codeが相対パスを上手く解決できず、代わりにfindコマンドで探し回るという場面を何度も見かけていました。
そこで先ほどの変数を使い絶対パスで指定するようにしたところ、エージェントがスクリプトの実行に失敗することは無くなりました。
$CLAUDE_SKILL_DIR/scripts/prepare_documentation.dartしかし、以前お話しした通り$CLAUDE_SKILL_DIRはClaude Code固有の機能ですから、他のエージェントがこのスキルを使う時に誤作動を起こす原因になりかねない、というのが悩ましいところです。
簡単ゆえに
「Skill.mdは単なるテキストファイルなので誰でも簡単に分かる・作れる」というがスキルの良いところですが、裏を返すとプログラムのような柔軟な制御は難しいということでもあります。これがプログラムなら、例えば共通部分を維持しつつフラグや環境変数で条件分岐させて、Claude Code専用の処理を入れるといったことも可能ですが、テキストファイルの場合そうはいきません。
エージェント毎にSkill.mdを用意する手も考えられますが、メンテナンス性のことを考えると少し厳しいです。自然言語で条件付けや分岐の指示を入れることはもちろん可能ですが、それはそれで、先ほどお話しした通り動作が不安定になりがちなので難しいところです。この辺りは標準化がもっと進めば解決されるかもしれませんね。
とはいえ
ネガティブな部分ばかり書いてしまいましたが、スキルという考え方自体とても気に入っています。作成したスキルも想定通り動いてくれているので、ひとまず満足しています。
Claude Codeマーケットプレイスやnpx skills、最近だとgh skillsなど、スキルのインストールやバージョン管理方法が割と早い段階から揃っており、MCPサーバーよりずっと手軽に扱える印象がありますね。ClaudeのAnthropicも、専門家エージェントを作るよりSkillを推しているようですし、今後もエコシステムの発達が期待できそうです。
個人的には、エンジニアではない人でもスキルを作ったり、中を見て理解したりといったことができる点がスキルの一番良いところかなと感じています。
おわり
ちなみに、私は会社配布のClaudecodeに⾃費でClaudeのサブスク代を追加していますから、使⽤量制限で困ることはほぼありません。
Claude Code配布と聞いて釣られそうになっている方がもしいれば、ぜひ採用ページをご覧ください。