svelte-ai

Svelte AI

このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• AI コーディングツール（Claude Code、Claude Desktop、Cursor、VS Code、Codex CLI、Copilot CLI、Antigravity CLI、OpenCode、Zed、GitHub Coding Agent）向けに、Svelte MCP サーバー（@sveltejs/mcp を介したローカル stdio、または https://mcp.svelte.dev/mcp を介したリモート）を設定するとき。
• 4 つの MCP ツール（list-sections、get-documentation、svelte-autofixer、playground-link）について説明するブロックを AGENTS.md（または CLAUDE.md / GEMINI.md）に追加するとき。
• AI セッションで svelte-task プロンプト、doc-section リソース、または 4 つの MCP ツールのいずれかを呼び出すとき。
• ドキュメントの検索（list-sections / get-documentation）や静的解析によるリンティング（svelte-autofixer）のスクリプトを実行するため、@sveltejs/mcp CLI を npx @sveltejs/mcp <command> として実行するとき。
• svelte-code-writer スキル（CLI ワークフロー）または svelte-core-bestpractices スキル（Svelte 5 のルーンに関するルール）をインストールまたは読み込むとき。
• 別のコンテキストウィンドウで .svelte / .svelte.ts / .svelte.js ファイルを扱う svelte-file-editor サブエージェントを設定するとき。

AI ツールを使用しない Svelte 5 の構文に関する質問だけを扱う場合は、このスキルを使用せず、代わりに svelte スキルを使用してください。

---

重要：Svelte AI の概要

Svelte チームは、組み合わせて、または個別に使用できる 4 つの連携した AI ツールを提供しています。

ツール	目的
指示	エージェントが利用可能なツールを認識できるよう、エージェントのセッションに常に注入される短いプロンプト
MCP サーバー（@sveltejs/mcp）	svelte.dev からドキュメントを取得するツール、プロンプト、リソースを提供し、生成されたコードを静的に解析します
スキル	エージェントに @sveltejs/mcp CLI と Svelte 5 のベストプラクティスを教える、必要に応じて読み込まれる指示（例：svelte-code-writer、svelte-core-bestpractices）
サブエージェント	別のコンテキストウィンドウで個別の操作を実行する、特定の作業に特化したエージェント（svelte-file-editor）

すぐに理解するためのモデル：

• MCP サーバー = ライブなプロトコルベースのアクセス（ツールはセッション内で実行されます）。
• スキル = エージェントが必要に応じて読み込む静的な Markdown。
• サブエージェント = 分離されたコンテキストを持つ委任先の作業者。
• CLI = MCP サーバーと同じエンジンを、シェルから操作するものです。

---

重要：AGENTS.md の標準

エージェントが利用可能な MCP ツールとその呼び出しタイミングを把握できるよう、このブロックを AGENTS.md（または CLAUDE.md / GEMINI.md）に追加してください。このブロックは npx sv add mcp によって自動的にインストールされます。

You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:

## Available Svelte MCP Tools:

### 1. list-sections
Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths.
When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.

### 2. get-documentation
Retrieves full documentation content for specific sections. Accepts single or multiple sections.
After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.

### 3. svelte-autofixer
Analyzes Svelte code and returns issues and suggestions.
You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.

### 4. playground-link
Generates a Svelte Playground link with the provided code.
After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.

主要な手順：

1. まず list-sections → 2. 関連するセクションに対して get-documentation → 3. コードを編集するたびに svelte-autofixer → 4. playground-link は、ユーザーからの依頼があり、かつコードがプロジェクトファイルに書き込まれていない場合に限って使用します。

---

重要：セットアップ — ローカルとリモート

MCP サーバーには 2 種類があります。

種類	コマンド / URL	最適な用途
ローカル（stdio）	npx -y @sveltejs/mcp	単一マシン、ネットワーク不要、npm によるバージョン固定
リモート（HTTP）	https://mcp.svelte.dev/mcp	常に最新のドキュメント、共有インスタンス、HTTPS 対応クライアントが必要

ローカルのセットアップ — AI クライアントの設定

クライアント	コマンド / ファイル
Claude Code	claude mcp add -t stdio -s [user|project|local] svelte -- npx -y @sveltejs/mcp
Claude Desktop	claude_desktop_config.json を編集 → { "mcpServers": { "svelte": { "command": "npx", "args": ["-y", "@sveltejs/mcp"] } } }
Codex CLI	~/.codex/config.toml に追加 → [mcp_servers.svelte] command = "npx" args = ["-y", "@sveltejs/mcp"]
Copilot CLI	/mcp add（対話形式）または ~/.copilot/mcp-config.json
Antigravity CLI	~/.gemini/config/mcp_config.json を編集
OpenCode	opencode mcp add → Local を選択 → npx -y @sveltejs/mcp
VS Code	コマンドパレット → MCP: Add Server... → Command (stdio) → npx -y @sveltejs/mcp
Cursor	コマンドパレット → View: Open MCP Settings → Add custom MCP
Zed	Svelte MCP Server extension をインストール

リモート設定 — AI クライアントの設定

クライアント	コマンド／ファイル
Claude Code	claude mcp add -t http -s [scope] svelte https://mcp.svelte.dev/mcp
Claude Desktop	Settings → Connectors → Add Custom Connector → URL https://mcp.svelte.dev/mcp
Codex CLI	~/.codex/config.toml に experimental_use_rmcp_client = true と [mcp_servers.svelte] url = "https://mcp.svelte.dev/mcp" を設定
Copilot CLI	/mcp add（対話形式）、または ~/.copilot/mcp-config.json に "url": "https://mcp.svelte.dev/mcp" を設定
Antigravity CLI	~/.gemini/config/mcp_config.json に "url": "https://mcp.svelte.dev/mcp" を設定
OpenCode	opencode mcp add → Remote を選択 → URL https://mcp.svelte.dev/mcp
VS Code	コマンドパレット → MCP: Add Server... → HTTP → URL https://mcp.svelte.dev/mcp
Cursor	コマンドパレット → View: Open MCP Settings → Add custom MCP（URL 形式）
GitHub Coding Agent	リポジトリの Settings → Copilot → Coding agent → "type": "http" を含む MCP 設定

プラグイン／マーケットプレイスからのインストール（利用可能な場合に推奨）：

• Claude Code：/plugin marketplace add sveltejs/ai-tools の後に /plugin install svelte
• OpenCode：OpenCode の設定の plugin に @sveltejs/opencode を追加
• Cursor：/add-plugin svelte（Cursor マーケットプレイス）
• Codex CLI：codex plugin marketplace add sveltejs/ai-tools の後に /plugins → svelte をインストール
• Copilot CLI：copilot plugin marketplace add sveltejs/ai-tools の後に copilot plugin install svelte@ai-tools

---

重要：MCP ツール

Svelte MCP サーバーは 4 つのツールを公開しています：

list-sections

すべてのドキュメントセクションの構造化リスト { title, use_cases, path } を返します。エージェントが取得すべき内容を把握できるよう、Svelte に関する会話では最初に呼び出してください。

get-documentation

1 つまたは複数のセクションパス（カンマ区切り、または配列）を受け取ります。list-sections の後に use_cases の文字列を分析し、実際に関連するセクションのみを取得してください。取得しすぎるとトークンを浪費します。

svelte-autofixer

Svelte コンポーネントまたはモジュールに対して静的解析を実行します。{ issues, suggestions, require_another_tool_call_after_fixing } を返します。結果が空になるまで、修正 → autofixer → 修正 → … のループで呼び出す必要があります。

playground-link

ユーザーのコードを含む一時的な Svelte Playground URL を生成します。ユーザーが確認した後、かつプロジェクトファイルが書き込まれていない場合にのみ呼び出してください。リンクにはプロジェクト全体がエンコードされ、別途保存されず、長くなることがあります。

---

重要：MCP リソース

doc-section

URI svelte://<slug>.md で参照される動的リソースです。選択したドキュメントページの llms.txt 形式にフラット化された内容を含みます。LLM に独自に取得させず、特定の知識をあらかじめ追加する場合に便利です（たとえば、タスクにトランジションが必要だと分かっている場合は svelte://transition.md を添付します）。

---

重要：MCP プロンプト

svelte-task

エージェントに Svelte コンポーネントまたはモジュールを作成させるときは、毎回このプロンプトをユーザーメッセージとして送信してください。次の内容が含まれています：

• 利用可能なドキュメントセクションのリスト（エージェントが list-sections を再度呼び出す必要はありません）。
• 厳格なルール：作成した Svelte コンポーネント／モジュールはすべて、問題がなくなるまで修正ループ内で svelte-autofixer に通す必要があります。
• playground-link に関するルール：確認後、かつファイルが書き込まれていない場合にのみ使用すること。Playground のエントリーポイントは App.svelte にする必要があります。

このプロンプトを選択し、<task> プレースホルダーにユーザーのリクエストを入力して送信してください。

---

重要：CLI サブコマンド

@sveltejs/mcp は MCP サーバーと CLI の両方として機能します。サブコマンドを指定すると、パッケージは MCP で通信する代わりに、結果を直接 stdout に出力します。

npx -y @sveltejs/mcp <command> [options]

利用可能なサブコマンド：

サブコマンド	用途	例
list-sections	すべてのドキュメントセクションを一覧表示します	npx -y @sveltejs/mcp list-sections
get-documentation <sections>	タイトルまたはパスでセクションを取得します（カンマ区切り）	npx -y @sveltejs/mcp get-documentation 'svelte/$state,svelte/await-expressions'
svelte-autofixer <code_or_path>	コードまたはファイルを lint します	npx -y @sveltejs/mcp svelte-autofixer src/routes/+page.svelte

svelte-autofixer のオプション：--svelte-version <4\|5>（デフォルトは 5）、--async（Svelte 5 の非同期解析を有効にします）。出力：{ issues, suggestions, require_another_tool_call_after_fixing }。

$ を含む引数は、変数置換を避けるためにシェルで引用符で囲んでください。可能な場合はファイルパスを渡してください。

---

重要：サブエージェント

svelte-file-editor

同梱されているサブエージェントです。ライフサイクル：

1. list-sections → get-documentation でコンテキストを収集します。
2. 対象の .svelte / .svelte.ts / .svelte.js ファイルを読み込みます。
3. Svelte 5 のベストプラクティスに従って編集します。
4. svelte-autofixer を呼び出して検証し、修正 → 再検証を繰り返します。
5. 変更の概要、autofixer の検出事項、および推奨事項を返します。

MCP ツールがない場合は svelte-code-writer スキルにフォールバックし、そのスキルもない場合は npx @sveltejs/mcp@latest -y --help のみを実行します。

svelte-code-writer（スキル）

CLI のみを使用するワークフローです。MCP ツールを利用できない場合、.svelte、.svelte.ts、または .svelte.js ファイルの作成／編集／解析時には必ず読み込んでください。ワークフロー：

1. 構文に確信が持てない場合：list-sections → get-documentation。
2. レビュー／デバッグの場合：コードに対して svelte-autofixer を実行します。
3. 最終確定の前に必ず検証します。

svelte-core-bestpractices（スキル）

Svelte 5 のイディオムです。コンポーネントの作成／編集／解析を依頼された場合は、すべての Svelte プロジェクトで読み込んでください。$state、$derived、$effect、$props、$inspect.trace、イベント、スニペット、{#each} のキー、CSS 変数、子コンポーネントのスタイリング、コンテキスト、非同期 Svelte、および避けるべきレガシー機能を扱います。

---

すぐに解決する方法

• エージェントが autofixer を呼び出さない：リポジトリのルートに AGENTS.md があり、上記の契約が記載されていることを確認してください。
• シェルで $ の展開によりインラインコードが壊れる：ソースを貼り付ける代わりにファイルパスを svelte-autofixer に渡すか、$ を \$ としてエスケープしてください。
• get-documentation の返却内容が多すぎる／トークンを消費しすぎる：use_cases の文字列に一致するセクションパスだけに絞ってください。
• Codex CLI のリモートモードが失敗する：config.toml に experimental_use_rmcp_client = true がありません（HTTP MCP に必要です）。
• Zed：手動で JSON を設定するより、公式の Svelte MCP Server 拡張機能をインストールしてください。
• Cursor CLI：プラグインはまだサポートされていません。/add-plugin svelte にはデスクトップアプリを使用してください。
• GitHub Coding Agent：リモート MCP URL のみがサポートされています。この環境では stdio 版は利用できません。
• Antigravity CLI：MCP 設定は ~/.config/ ではなく、~/.gemini/config/mcp_config.json にあります。

---

注意点

• playground-link ツールは、プロジェクト全体をリンクにエンコードしたURLを作成します。リンクは長くなる可能性があり、エラートラッカーに記録しないでください。
• get-documentation はトークン消費量が多いため、タスクに合致するセクションだけを取得してください。カタログ全体を再取得しないでください。
• $derived は関数ではなく式です。関数本体が必要な場合は、$derived.by(() => …) を使用してください。
• Effect はサーバー上では実行されません。Effect の本体を if (browser) { ... } で囲まないでください。
• 非同期 Svelte（await 式、ハイドレーション可能）には、Svelte 5.36 以降と svelte.config.js の experimental.async: true が必要です。
• オートフィクサーは、大きく変更されないオブジェクトへの $state の使用をパフォーマンス上の問題とみなします。API レスポンスには $state.raw(...) を使用してください。
• 各ブロックのキーは項目を一意に識別する必要があります。ループインデックスをキーとして使用しないでください。
• キー付きの {#each} ブロックを優先してください。オートフィクサーはキーのないリストを指摘します。
• コンポーネントのトップレベルで宣言されたスニペットは、<script> から参照でき、コンポーネントの状態を参照しない場合は <script module> からエクスポートすることもできます。
• サブエージェント（svelte-file-editor）は別のコンテキストウィンドウを使用します。メインエージェントのコンテキストを小さく保つため、大規模な編集タスクはサブエージェントに委任してください。

---

FAQ

Q: AGENTS.md、CLAUDE.md、GEMINI.md の違いは何ですか？ A: 考え方は同じです。AGENTS.md はツール横断の標準（agents.md）です。Claude Code は CLAUDE.md を、Gemini CLI は GEMINI.md を読み取ります。Svelte の規約はどれでも同じように機能します。

Q: ローカル MCP とリモート MCP のどちらを選べばよいですか？ A: オフライン環境、CI、バージョンの固定にはローカルを選んでください。常に最新のドキュメントを利用でき、インストール不要にするにはリモートを選んでください。どちらも同じツールを公開するため、コードを変更する必要はありません。

Q: エージェントが svelte-autofixer をスキップするのはなぜですか？ A: MCP クライアントにツールが登録されていない（インストールコマンドを再実行してください）か、AGENTS.md が存在しない可能性があります。Codex CLI のユーザーは、experimental_use_rmcp_client = true になっていることを確認してください。

Q: ファイルパスを指定してオートフィクサーを実行できますか？ はい。npx -y @sveltejs/mcp svelte-autofixer src/routes/+page.svelte を実行してください。

Q: スキルとサブエージェントの違いは何ですか？ A: スキルは、必要に応じてエージェントが読み取る Markdown で、コストを抑えられます。サブエージェントは、それぞれ独自のコンテキストウィンドウを持つ委任先のワーカーです。コストは高くなりますが、メインのコンテキストを整理した状態に保てます。

Q: svelte-task は引数を受け取りますか？ A: はい。プロンプト本文の <task> プレースホルダーを実際のタスクに置き換えてから、ユーザーメッセージとして送信してください。

Q: リモート MCP の URL は固定ですか？ はい。https://mcp.svelte.dev/mcp は公式の、常に最新のエンドポイントです。

Q: svelte-file-editor サブエージェントはどこにインストールすればよいですか？ Claude Code／Codex／Copilot／OpenCode のプラグインに自動で同梱されています。OpenCode では、~/.config/opencode/svelte.json で model／temperature／top_p／maxSteps を固定することもできます。

Q: Svelte AI は Svelte 4 のプロジェクトで実行できますか？ はい。svelte-autofixer --svelte-version 4 を実行してください。他のツール（list-sections、get-documentation）は両方のバージョンのドキュメントを返します。

---

リファレンス一覧

• 例：examples/README.md
• セットアップ対応表：references/setup-clients-reference.md
• ツールリファレンス：references/mcp-tools-reference.md
• リソースリファレンス：references/mcp-resources-reference.md
• プロンプトリファレンス：references/mcp-prompts-reference.md
• CLI リファレンス：references/cli-reference.md
• サブエージェントリファレンス：references/subagents-reference.md
• アーキテクチャ：references/overview-reference.md