Claude Codeのhuggingface-skillsプラグインでhf-cliとTRL学習を回す
Claude CodeにHugging Faceのスキル集を入れると、hf CLIの操作とTRLによる学習ジョブをClaudeに任せられます。入れ方が2通りある点、学習スキルの使い分け、課金と保存のつまずきどころをまとめます。
Hugging Faceのスキル集(huggingface-skills)をClaude Codeに入れると、Hubの操作を担う hf-cli と、TRLでの学習を担うスキルが使えるようになります。モデルの取得、データセットの検索、クラウドGPUでのファインチューニングまでを、自然文の依頼から進められます。
先に押さえておきたい点が2つあります。入れ方が掲載場所によって違うこと、そして学習スキルは依頼するとすぐジョブを投入する作りで、課金が絡むことです。
入れ方は2通りの説明がある
Claude側のマーケットプレイスの掲載ページと、スキル集のリポジトリの説明は、入れ方が揃っていません。
| 見る場所 | 書かれている内容 |
|---|---|
| マーケットプレイスの掲載ページ | 書かれている内容8つのスキルを含むプラグイン。/hugging-face-model-trainer、/hugging-face-datasets、/hugging-face-evaluation で呼べる |
| リポジトリのREADME | 書かれている内容マーケットプレイスに出すのは hf-cli だけ。ほかのスキルは hf skills add <skill-name> で後から足す |
掲載ページは、モデル学習(SFT・DPO・GRPO・報酬モデル)、データセット管理、評価、計算ジョブの実行、Trackioによる実験追跡、論文の公開、ツール作成、hf CLI経由のHub操作の8つを挙げています。一方READMEは、クライアント向けのマーケットプレイス定義を hf-cli に絞っていると説明しています。リポジトリ側のAvailable skillsには25個のスキルが並び、掲載ページの名前とも一致しません。
どちらの状態で入るかは、入れたあとにセッションで確かめるのが確実です。手元で見えたスキルを正としてください。
手順: hf-cliを入れて、足りないスキルを追加する
READMEが示すClaude Codeの手順は3段階です。
huggingface-skillsの導入
- 1
リポジトリをマーケットプレイスとして登録する
Claude Codeのセッション内でスラッシュコマンドを実行します。
- 2
hf-cliスキルを入れる
最初に入れるスキルとして、READMEは
hf-cliを勧めています。 - 3
必要なスキルをhf CLIで足す
学習やデータセットなどのスキルは、
hfコマンドのskillsサブコマンドで追加します。
/plugin marketplace add huggingface/skills
/plugin install hf-cli@huggingface/skillshf コマンド自体はスキルの前提になります。hf-cli のスキル本文には、インストーラーのコマンドが curl -LsSf https://hf.co/cli/install.sh | bash -s と記されています。入っていれば、追加と更新は次のように進められます。
hf auth login
hf skills list
hf skills add huggingface-llm-trainer
hf skills updatehf skills の配下にあるのは add・list・preview・update の4つです。hf skills preview は、生成された hf-cli のSKILL.mdを標準出力に出します。hf-cli のスキルは手元にインストールされたCLIから生成される作りで、CLIを更新したら hf skills add --force で作り直せます。
認証は HF_TOKEN 環境変数が推奨されています。--token で毎回渡すより、環境変数に置く形です。
hf-cliスキルで任せられる操作
hf-cli は、hf コマンドの一覧をClaudeに教えるスキルです。READMEの言い方では「Hubへのアクセスを渡したいだけなら、まずこれ」という位置づけです。スキル本文には、次のようなコマンド群が載っています。
hf-cliに載っている主なコマンド群
取得とアップロード
hf downloadとhf uploadで、モデル・データセット・Space・カーネルを扱います。--dry-runで実際に落とさず確認できます。データセットの照会
hf datasets listやinfoに加えて、hf datasets sqlがDuckDBでParquetに対してSQLを実行します。ダウンロードせずに中身を覗く用途です。ジョブとバケット
hf jobs runでHugging Faceのインフラ上にジョブを投げ、hf jobs logsでログを追います。hf bucketsは学習の保存先のような大きなファイル置き場です。Space・Endpoint・Webhook
hf spacesでSpaceの設定と待機、hf endpointsで推論エンドポイントのデプロイ、hf webhooksでWebhookを管理します。
ジョブ関連は課金に直結するため、hf jobs run のオプションを知っておくと依頼の精度が上がります。--flavor でハードウェア、--timeout で制限時間、--dry-run で投入前の確認、--secrets でトークンの受け渡しを指定します。hf jobs hardware を使うと、選べるハードウェアの一覧が出ます。
学習スキルはどれを呼ぶか
TRLを扱うスキルは、リポジトリ内に役割の違う複数があります。
| スキル | 担当 | 向く場面 |
|---|---|---|
trl-training | 担当TRLのPython APIとCLIでの学習コードの書き方・デバッグ | 向く場面手元や自前の環境で学習コードを書く |
huggingface-llm-trainer | 担当Hugging Face Jobs上での学習、GGUF変換、ハードウェア選定、コスト見積もり | 向く場面GPUが手元になく、クラウドで回す |
huggingface-vision-trainer | 担当物体検出・画像分類・SAM系の学習 | 向く場面言語モデル以外を学習する |
huggingface-trackio | 担当学習実験の追跡と可視化 | 向く場面学習の途中経過を見たい |
trl-training は、手法ごとのTrainerとデータ形式の対応を教えるスキルです。SFTTrainer は言語モデリングかプロンプト・補完形式、DPOTrainer はchosen / rejectedの選好ペア、GRPOTrainer はプロンプトのみと報酬関数、KTOTrainer はサンプルごとの真偽ラベル、RewardTrainer は選好ペアから報酬モデルを学習します。会話形式のデータではチャットテンプレートが自動で適用されるので、自分で適用しないよう書かれています。
GRPOの報酬関数は、キーワード引数の prompts・completions・completion_ids・trainer_state と、データセットの追加列を受け取ります。使わない引数は **kwargs で受け流し、補完ごとに1つの浮動小数を返す形です。会話形式のデータでは、completions が文字列ではなくメッセージのリストになる点も明記されています。
huggingface-llm-trainer は、これに加えてUnslothの使い分けも持っています。GPUメモリが足りないとき、13B超のモデル、視覚言語モデルのいずれかなら、通常のTRLよりUnslothを選ぶ基準が示されています。
Hugging Face Jobsで学習を回す前提
huggingface-llm-trainer の前提チェックリストには、見落とすと損をする項目が並んでいます。
ジョブを投げる前に確かめる4点
- アカウントがPro・Team・Enterpriseのいずれかであること。Jobsは有料プランが必要と書かれています
- ジョブ設定で
secrets={"HF_TOKEN": "$HF_TOKEN"}を渡し、トークンに書き込み権限があること - 学習設定に
push_to_hub=Trueとhub_model_idを入れること。ジョブの環境は使い捨てで、終了時にファイルが消えます - タイムアウトを学習時間より長くすること。既定は30分で、超えるとジョブが止まり、進捗が失われます
タイムアウトの目安として、スキルは本番規模の3〜7Bモデルで4〜6時間を挙げ、さらに20〜30%の余裕を足すよう書いています。ハードウェアは、1B未満なら t4-small、3〜7Bなら a10g-small か a10g-large が推奨の目安です。7Bを超えるならLoRAを前提にします。時間単価の目安もスキルの表にありますが、価格は変わりうるので、投入前に hf jobs hardware と見積もりで確かめるのが安全です。
見積もりには、リポジトリ付属の scripts/estimate_cost.py を使います。モデル、データセット、ハードウェア、データ件数、エポック数を渡すと、所要時間とコスト、推奨タイムアウトが出ます。
依頼文の組み立て方
スキルの指示は、学習を頼まれたらスクリプトを作って即座にジョブを投入する設計です。「学習して」とだけ頼むと、見積もりの確認なしに課金が始まる動きになりえます。投入前に止めたいときは、依頼文に確認の手順を入れます。
学習の依頼文に確認の段を入れる
そのまま頼む
「このデータセットでQwenをSFTして」と頼むと、スキルの指示どおりスクリプト作成からジョブ投入までが一気に進みます。
見積もりと検証を挟む
次のように、検証・見積もり・確認の順を指定します。
huggingface-llm-trainerスキルでQwen/Qwen2.5-0.5BをSFTしたい。
データセットはtrl-lib/Capybara。
1. データセットの形式をSFT向けに検証する
2. estimate_cost.pyでa10g-largeの時間と費用を出す
3. push_to_hub・hub_model_id・HF_TOKENの設定を確認する
4. ここまでの結果を見せて、私が承認してからジョブを投入するデータセットの検証は、スキルが勧めている工程です。形式が合わないデータで学習を始めると、GPU時間を使ったあとに失敗します。スキル内の手順では、検証の目安は約0.01ドル・1分未満のCPU実行とされており、投入前に挟む価値があります。
投入後の確認も依頼文で決められます。スキルは、状況確認を自動でポーリングせず、利用者が頼んだときだけログを見る方針です。経過を見たいときは、「ジョブIDのログを見て」と明示します。CLIで見るなら hf jobs logs <ジョブID> です。
コネクタとの違いと、重ねて使う場合
Hugging Faceには、スキル集とは別にClaudeのコネクタもあります。担当が違うので、用途で選びます。
| huggingface-skills | Hugging Faceコネクタ | |
|---|---|---|
| 形 | huggingface-skillsスキル(手順書とスクリプト)のプラグイン | Hugging FaceコネクタMCPサーバーへの接続 |
| 得意 | huggingface-skillshf CLIの操作、学習ジョブ、GGUF変換 | Hugging Faceコネクタモデル・データセット・論文の検索、Gradioアプリの呼び出し |
| 学習 | huggingface-skillsできる(Jobsに投入) | Hugging Faceコネクタ掲載ツールに学習はない |
コネクタの接続と使えるツールは、ClaudeとHugging Faceの連携手順にまとまっています。スキル側の huggingface-llm-trainer は、ジョブ投入に hf_jobs() というMCPツールを第一の手段に指定しています。このMCPツールが使えない環境では、hf jobs のCLIで代用する手順が用意されています。
つまずきやすい点
落とし穴
hf jobs uv run はフラグをスクリプトより前に置く
スキルのCLI手順には、フラグをスクリプトのURLより後ろに置くと無視されると書かれています。hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "<スクリプトのURL>" の順です。run uv と逆にしたり、--secrets を単数形の --secret と書いたりしても失敗します。Claudeが組んだコマンドは、実行前に順序を見ておくと安全です。
もう1点、旧コマンドの huggingface-cli は非推奨で、hf に置き換わっています。古い記事の手順で huggingface-cli を使っていても、スキル側は hf を前提にします。認証系は hf auth の配下にまとまり、ログイン確認は hf auth whoami です。
スキル全般のしくみは、Claude.aiのプラグイン機能の解説で、スキル・コネクタ・Claude Codeの違いとして整理されています。データセットの中身を点検する別の例は、FiftyOneのスキルで画像データセットを検証する手順にあります。
まとめ
入れるのは hf-cli からで足ります。学習やデータセットのスキルは、必要になった時点で hf skills add で足せます。マーケットプレイスの掲載ページとREADMEで説明が食い違うため、入れたあとに見えるスキル名を確かめてから依頼文を書くと、呼び出しの空振りを避けられます。
学習は、課金と保存設定が絡む作業です。検証・見積もり・承認の順を依頼文に書き、push_to_hub とタイムアウトを投入前に確認する運用なら、スキルの「すぐ投入する」挙動に引っ張られずに使えます。