Claude Codeにliquid-skillsとliquid-lspを入れてLiquidを書かせる

Shopifyは、Liquidテーマの開発向けにClaude Codeのプラグインを2本出しています。liquid-lsp は言語サーバーをつないで、編集直後の診断とコード探索をClaudeに渡すプラグインです。liquid-skills はLiquidの書き方・CSS/JS/HTMLの規約・アクセシビリティの型を、3つのスキルとして教えるプラグインです。

2本は役割が重ならないので、両方入れるのが基本になります。入れ方は2通りあり、Shopifyのマーケットプレイスを追加する方法と、Anthropicの公式マーケットプレイスから入れる方法です。

liquid-lspとliquid-skillsは何が違うのか

liquid-lsp と liquid-skills は、同じリポジトリ(Shopify/liquid-skills)に入った別々のプラグインです。リポジトリはそれ自体がClaude Code用のプラグインマーケットプレイスとして作られています。

前者は「書いた結果を検査する側」、後者は「書く前に知っておくべきことを渡す側」です。片方だけでも動きますが、効く場面が違います。テーマ開発そのものの進め方、つまり shopify theme check を検証コマンドにした反復やhooksの組み方は、Claude CodeでShopifyテーマ開発を進める手順で扱っています。ここでは2本のプラグインの導入に絞ります。

導入手順 — Shopify CLIを入れてから2本を入れる

liquid-lsp が起動するのは shopify コマンドです。プラグインにはサーバー本体が含まれないため、先にShopify CLIを入れます。

npm install -g @shopify/cli
shopify theme language-server --help

Homebrewなら brew tap shopify/shopify のあとに brew install shopify-cli でも入ります。2行目は、言語サーバーのコマンドが PATH 上で見つかるかの確認です。ここで失敗するなら、プラグインを入れても動きません。

ルートA — Shopifyのマーケットプレイスを追加する

リポジトリのREADMEが示す手順です。Claude Codeを起動して、次の3行を順に実行します。

/plugin marketplace add Shopify/liquid-skills
/plugin install liquid-lsp@liquid-skills
/plugin install liquid-skills@liquid-skills

@liquid-skills の部分は、追加したマーケットプレイスの名前です。

ルートB — 公式マーケットプレイスから入れる

Anthropicの公式マーケットプレイスの一覧にも、liquid-lsp と liquid-skills の両方が載っています。公式マーケットプレイスは、対話モードで初めて起動したときにClaude Codeが自動で追加します。マーケットプレイスの追加は要りません。

/plugin install liquid-lsp@claude-plugins-official
/plugin install liquid-skills@claude-plugins-official

claude.com/marketplaceのプラグインページにある「Claude Code」ボタンは、claude plugin install <名前>@claude-plugins-official の形でコマンドをコピーします。シェルから入れたいときはこの形です。

どちらのルートでも、/plugin install はその場で入れずに /plugin パネルの詳細を開きます。プラグインはフックやMCPサーバーを含み得るので、中身を見てからスコープを選ぶ流れです。入れた結果は、有効になった旨のメッセージか Run /reload-plugins to apply. のどちらかで返ります。

スコープはチームで決める

チーム全員で使うなら、プロジェクトスコープで入れます。設定は .claude/settings.json に書かれてコミットできますが、コミットしただけでは各自の端末にダウンロードされません。メンバーは、それぞれ一度 claude plugin install <名前>@<マーケットプレイス> --scope project を実行します。

動いているかを確かめる

liquid-lsp の言語サーバーは、Claudeが .liquid ファイルを最初に編集したときに起動します。確認の手順は次のとおりです。

1. テーマのリポジトリでClaude Codeを起動する
2. Claudeに、セクションファイルへ存在しないフィルターを使うLiquidを書かせる
3. 編集の下に Found N new diagnostic issues in M files (ctrl+o to expand) が出るかを見る
4. 内容を読むならCtrl+Oを押す

診断の行が出ないときは、/plugin を開いてErrorsタブを見ます。Executable not found in $PATH: "shopify" と書かれていれば、Shopify CLIが claude を起動したシェルの PATH にありません。CLIを入れてから、そのシェルで新しいセッションを始めます。claude --debug のログには LSP server <name> failed to start: <reason> の形で理由が残ります。

liquid-lspはClaudeに何を渡すのか

プラグインの設定は、.lsp.json 1枚だけです。実際の中身は次のとおりです。

{
  "theme-language-server": {
    "command": "shopify",
    "args": ["theme", "language-server"],
    "extensionToLanguage": {
      ".liquid": "liquid",
      ".json": "json"
    }
  }
}

.liquid と .json の2つの拡張子を、このサーバーが受け持つ設定です。テーマには templates/*.json のようなJSONも含まれるため、.json の編集でも診断の対象になります。

言語サーバーが動いている間、Claudeが得るものは2つです。

• 編集後の診断: ファイルを編集・作成するたびに、サーバーが報告するエラーと警告がClaudeに返る。ビルドの工程を挟まずに、自分の書いた誤りに気づける
• コード探索のLSPツール: 定義へのジャンプ、参照の検索、型情報の取得、ファイル内のシンボル一覧、ワークスペース横断のシンボル検索、インターフェースの実装の検索、呼び出し階層のたどり方まで使える。読み取り専用のツール

Shopify側のドキュメントによると、このテーマ言語サーバーの機能は、ホバー時のドキュメント表示、コード補完、コード整形、Theme Check、コード探索です。どの機能がClaudeへの診断として返るかは、ドキュメントに内訳がありません。

liquid-skillsの3本は何を教えるのか

liquid-skills は3つのスキルを持ちます。スキルは、説明文に書かれた条件に合う作業のときに使われます。

スキルの本文を読むと、何を教えているかが具体的に分かります。たとえば liquid-theme-standards は、{% stylesheet %} の中ではLiquidが処理されない、と明記しています。動的な値は style 属性でCSSカスタムプロパティとして渡す、という書き方です。

<div
  class="hero"
  style="--bg-color: {{ section.settings.bg_color }}; --padding: {{ section.settings.padding }}px;"
>

{% stylesheet %} の中に {{ section.settings.bg_color }} を書いても動きません。このように、テーマ固有の落とし穴がスキルの本文に書かれています。

shopify-liquid-themes は、テーマのフォルダ構成の使い分けも表にしています。ストア運営者がエディタで編集するモジュールはセクション、入れ子にできる小さな部品はブロック、ストア運営者が編集しない再利用部品はスニペットです。ブロックから別のブロックを {% render %} できないため、共通ロジックはスニペットに置く、という判断軸も入っています。

liquid-theme-a11y は、コンポーネントごとにHTML要素とARIAの組み合わせを決めた表を持ちます。モーダルとカートドロワーは <dialog>、展開部分は <details> / <summary> が基本で、ARIAは標準の意味で足りないときだけ足す、という順序です。

つまずきやすい点

言語サーバーはクラウドセッションでは動きません。ClaudeのLSPツールは、プラグインを入れるまで無効です。クラウドセッションでは、Claude Codeがプラグインの言語サーバーを起動しないため、診断もコード探索も使えません。ローカルの端末で使う前提です。

LSPプラグインの推奨ダイアログが出ることがあります。 shopify が PATH にあり、対応するプラグインが未導入のとき、Claudeが .liquid を編集するとLSP plugin recommendationが出ます。「Yes, install」を選ぶとユーザー単位で入り、新しいセッションで有効になります。このダイアログは1セッションに1回までです。選ばずに30秒たつと無視した扱いになり、5回無視すると出なくなります。

もう一度出したいときは、~/.claude.json から lspRecommendationDisabled と lspRecommendationIgnoredCount の2つのキーを消します。「Never for this plugin」を選んだプラグインは、同じファイルの lspRecommendationNeverPlugins から 名前@マーケットプレイス の形のIDを消すと、また提案されます。

liquid-lsp はAnthropicの管理ではありません。Claude Codeのドキュメントも、liquid-lsp だけはShopifyが保守していて、公式マーケットプレイスは一覧に載せているだけだと書き分けています。不具合の連絡先はShopifyのリポジトリです。

メモリを食うときは止めます。Claude Codeのドキュメントは、プロジェクト全体を索引化する言語サーバー(rust-analyzerやpyrightなど)がメモリを使うことがあると説明しています。重いと感じたら、セッション内で /plugin disable liquid-lsp を実行し、Claude標準の検索ツールに任せる手があります。

手元で中身を試したいときは、リポジトリをクローンして claude --plugin-dir ./plugins/liquid-lsp を使います。インストールせずに、そのセッションだけプラグインを読み込めます。

2本をどう使い分けるか

どちらを先に入れるかは、困っている症状で決まります。

• Claudeが存在しないフィルターや壊れたスキーマを書く: liquid-lsp。編集の直後に診断が返るので、誤りに気づく手前の往復が減ります
• 動くが、BEMやデザイントークンの規約から外れる: liquid-skills の liquid-theme-standards
• ECのカードやドロワーでキーボード操作が通らない: liquid-skills の liquid-theme-a11y
• 命名規約やチーム固有の設計を守らせたい: プラグインではなく、CLAUDE.mdに書く領域

プラグインのスキルは汎用の規約です。自社テーマのクラス名の接頭辞や、触ってはいけないファイルまでは知りません。それはCLAUDE.mdの役目で、役割を分けると両方が噛み合います。プラグインの仕組みそのもの、つまりマーケットプレイスの追加や自作はClaude Codeプラグイン完全ガイドにまとまっています。

まとめ

導入はShopify CLIを先に入れ、liquid-lsp と liquid-skills を同じ要領で入れるだけです。入れたあとは、.liquid の編集直後に診断の行が出るかで動作を確かめられます。出ないときは、/plugin のErrorsタブで shopify コマンドの見つかり方を見るのが最短です。

規約の面はスキルが、誤りの検出は言語サーバーが分担します。自社固有のルールまでは両方とも知らないので、そこはCLAUDE.mdで補います。