1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@thayate

IBM BobのSkills構築 - watsonx.aiを使った開発の効率化

1
Posted at

はじめに

IBM Bobに、Skills という仕組みがあります。
Skill とは、特定のタスクに特化したガイド付き指示セットのことで、Bob に登録することでコード生成や実装支援をより的確に行えるようになります。

Bobを使いこなすための勉強の一環としてSkillsを自分で作ってみました。作成したSkillsはwatsonx.aiのAPIを使った開発のためのSkillsです。
本記事ではそのSkillsをBobと構築していった経験をまとめます。

この記事で得られること:

  • Bob Skills がどういう仕組みで動くかの理解
  • Skill を設計・構成するときの考え方
  • 実際に作った watsonx-integration Skill の構造と工夫した点

Bob の Skills とは

Bob Docsの説明（https://bob.ibm.com/docs/ide/features/skills）によると、Skills は以下のような位置づけです。

専門的なワークフロー用の再利用可能な命令セットを作成します。カスタムワークフローを定義し、サポートファイルを追加し、一貫した結果を得るためにBobに専門的なタスクを教えます。

つまり Skills は 「Bobへの文脈付き命令書」 です。通常のプロンプトと違うのは、参照ドキュメントやテンプレートを一緒に束ねて、Bob が一連の手順を踏んで作業できるように設計できる点です。

Skills の基本構造

最小構成は SKILL.md 一枚です。ここに名前・説明・手順を書きます。

---
name: my-skill
description: このSkillが何をするかの説明（Bobがいつ使うか判断する）
---

# My Skill

<Steps>
<Step>
## 1. 最初にやること
...
</Step>
<Step>
## 2. 次にやること
...
</Step>
</Steps>

<Steps> / <Step> タグで手順を構造化することで、Bob が段階的に作業を進めます。

なぜ watsonx.ai を題材に選んだか

watsonx.ai を使う開発では、認証の書き方・モデルIDの選択・パラメータ設定など、毎回同じことを（Bobが）調べることになっていました。これを Skill に落とし込めれば生産性が上がると考えました。
また、Skillsを作成する前の開発では、古いドキュメント参照してしまっているのか、すでにwatsonx.aiで使えないモデルやAPIを使って実装してしまうことがありました。毎回手動で直していたので、Skillsを使うのにもってこいだと考えました。

作った Skill のファイル構成

最終的な構成は以下です。最初は SKILL.md だけでしたが、作りながら参照ファイルを増やしていきました。

watsonx-integration/
├── SKILL.md                       # Skillのエントリーポイント（手順定義）
├── model-catalog.md               # モデル選定ガイド
├── sdk-reference.md               # SDKリファレンス
├── IMPROVEMENT_SUMMARY.md         # 改善記録
├── templates/
│   ├── python-basic.py            # テキスト生成の実装例
│   ├── python-chat.py             # マルチターンチャットの実装例
│   └── python-streaming.py        # ストリーミングの実装例
├── checklists/
│   └── integration-checklist.md  # 実装前後の確認チェックリスト
└── guides/
    └── authentication-guide.md    # 認証の詳細ガイド

ポイントは SKILL.md が他のファイルを参照する構造 にしたことです。Skill 本体はシンプルに保ちつつ、詳細は専用ドキュメントに分離しています。
多分これで無駄にコンテキストを圧迫することなく、Bob Coinも節約できるのだと思います。

SKILL.md の設計

description フィールドが重要

---
name: watsonx-ai-integration
description: IBM watsonx.ai基盤モデル（LLM）をアプリケーションに統合するための本番環境対応Pythonコードを生成します。watsonx.ai APIの呼び出し、ibm-watsonx-ai SDKの使用、IBM Graniteまたは他の基盤モデルを使用したテキスト生成、チャット、ストリーミング、埋め込みの実装が求められた場合に使用します。
---

description は Bob がこの Skill を使うタイミングを判断する ために使われます。「いつ発動するか」を具体的に書くのがコツです。「watsonx.ai API」「ibm-watsonx-ai SDK」「Granite」などのキーワードを明示することで、関連するリクエストを受けたときに自動的にこの Skill が選ばれます。

ステップの設計方針

各ステップは「Bob がそのステップで何を決定・実装するか」を明確にしました。

<Steps>

<Step>
## 1. 要件の明確化
コードを書く前に以下を確認してください：
- タスクタイプ: テキスト生成 / チャット / ストリーミング / 埋め込み / RAG
- モデル: エンタープライズ向けには IBM Granite を推奨（model-catalog.md を確認）
- 認証: IBM Cloud（APIキー）または Cloud Pak for Data

未指定の場合のデフォルト:
- モデル: `ibm/granite-4-h-small`
- 認証: IBM Cloud
- スコープ: project_id
</Step>

<Step>
## 2. 認証とクライアントのセットアップ
（認証コードの雛形と注意事項...）
</Step>

...

</Steps>

学んだこと: ステップを細かく分けるほど、Bob の出力が安定しました。「認証」「実装」「パラメータ設定」「エラーハンドリング」を一つのステップにまとめると、どれかが抜ける。

参照ファイルの工夫

model-catalog.md — 「どのモデルを使うか」の判断を Skill に埋め込む

モデルIDは間違えやすく、また選択基準がユースケースで変わります。SKILL.md に全部書くと長くなりすぎるので、独立したカタログに分離しました。

Bobが参照しやすいように ユースケース → モデルIDのフロー を決定木形式で書いています：

コード生成？
  → Yes: ibm/granite-8b-code-instruct
  → No:
    画像入力あり？
      → Yes: meta-llama/llama-3-2-11b-vision-instruct
      → No:
        IBM補償モデル優先？
          → Yes: ibm/granite-4-h-small（デフォルト）
          → No: meta-llama/llama-3-3-70b-instruct

sdk-reference.md — 「正しいインポートとパラメータ」の単一情報源

SDK のインポートパスやパラメータ名は間違えやすく、調べなおすコストが高い部分です。SKILL.md から「完全なパラメータは sdk-reference.md を確認」と参照させることで、Skill 本体をシンプルに保ちながら正確さを担保しています。

| パラメータ | 型 | 説明 |
|---|---|---|
| `MAX_NEW_TOKENS` | int | 生成する最大トークン数 |
| `TEMPERATURE` | float 0–2 | ランダム性。低いほど決定的 |
| `DECODING_METHOD` | str | `"greedy"` または `"sample"` |
...

checklists/integration-checklist.md — 実装品質のガードレール

コード生成後に「ちゃんと本番対応になっているか」を確認するためのチェックリストです。
Skill の最終ステップで「このチェックリストに沿って確認してください」と参照させています。

### 実装後の確認
- [ ] 認証情報がソースコードにハードコードされていない
- [ ] すべての必須環境変数がドキュメント化されている
- [ ] エラーハンドリングが実装されている
- [ ] .gitignore に .env を追加している

Skill が生成するコードの例

この Skill を使って Bob に「watsonx.ai でチャットアプリを作って」と依頼すると、以下のような本番対応コードが一発で出てきます。

生成されるコードのポイント

import os
import logging
from ibm_watsonx_ai import Credentials, APIClient
from ibm_watsonx_ai.foundation_models import ModelInference
from ibm_watsonx_ai.metanames import GenTextParamsMetaNames as GenParams

logger = logging.getLogger(__name__)


def main():
    # 認証情報は環境変数から（Skillの Step 2 が徹底させる）
    credentials = Credentials(
        url=os.environ["WATSONX_URL"],
        api_key=os.environ["WATSONX_API_KEY"]
    )
    client = APIClient(credentials, project_id=os.environ["WATSONX_PROJECT_ID"])

    # パラメータは必ず明示（Skillの Step 4 が徹底させる）
    params = {
        GenParams.MAX_NEW_TOKENS: 512,
        GenParams.TEMPERATURE: 0.7,
        GenParams.TOP_P: 0.9,
        GenParams.DECODING_METHOD: "sample",
    }

    model = ModelInference(
        api_client=client,
        model_id="ibm/granite-4-h-small",  # model-catalog.md が選定
        params=params
    )

    messages = [
        {"role": "system", "content": "あなたは親切なアシスタントです。"},
        {"role": "user", "content": "量子コンピューティングを簡単に説明してください。"}
    ]

    response = model.chat(messages=messages)
    print(response["choices"][0]["message"]["content"])

Skill がなければ「認証情報のハードコード」「パラメータの省略」「エラーハンドリングなし」といった問題が発生しがちです。Skill が各ステップでガイドすることで、これらが自動的に守られます。

作ってみて気づいた Skill 設計のコツ

1. SKILL.md は薄く、参照ファイルを厚く

最初は SKILL.md にすべて書こうとして、ファイルが500行になりました。参照ファイルに分離することで SKILL.md が読みやすくなり、Bob の動作も安定しました。

2. デフォルト値を明示する

「ユーザーが指定しない場合は〇〇を使う」を明示することで、Bob が迷わなくなります。
これを明示する前は既に提供が終了してしまっているモデルを指定してしまうことが多く、修正するのが手間でした。

未指定の場合のデフォルト:
- モデル: `ibm/granite-4-h-small`
- 認証: IBM Cloud（api_key + url）
- スコープ: project_id

3. 「なぜそうするか」を書く

「ソースコードに認証情報をハードコードしないでください — 環境変数を使用してください」
ただのルールではなく理由も添えると、Bob の判断の精度が上がります。

4. チェックリストで品質を担保する

コード生成後のレビューステップにチェックリストを組み込むことで、生成物の品質を一定以上に保てます。Skill の最後のステップとして必ず実行させる設計にしました。

改善のサイクル

初期バージョンを作ったあと、実際に Skill を使ってコードを生成してみることで問題点を発見しました。
「Skill を使ってコードを生成 → 品質を評価 → Skill 自体を改善」というサイクルが、Skill 開発の基本的な進め方だと学びました。

まとめ

Bob の Skills は、繰り返し発生する開発タスクを「手順書 + 参照ドキュメント」として構造化する仕組み です。

watsonx.ai 統合を題材に Skill を作ってみて：

  • 学習面: SKILL.md の description でトリガーを制御する仕組み、<Steps> で手順を分解する設計など、Skills の仕組みを実践的に理解できた
  • 生産性面: 認証・モデル選択・パラメータ設定・エラーハンドリングが毎回自動でガイドされるようになり、コードレビューの指摘が大幅に減った

「繰り返しやっている開発作業で、毎回同じことを調べている」という場面があれば、Skill 化する価値があります。

参考

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?