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 使用远程服务）。
• 添加 AGENTS.md（或 CLAUDE.md / GEMINI.md）区块，说明四个 MCP 工具（list-sections、get-documentation、svelte-autofixer、playground-link）。
• 在 AI 会话中调用 svelte-task 提示词、doc-section 资源或四个 MCP 工具中的任意一个。
• 将 @sveltejs/mcp CLI 作为 npx @sveltejs/mcp <command> 运行，以通过脚本查找文档（list-sections / get-documentation）或进行静态分析检查（svelte-autofixer）。
• 安装 / 加载 svelte-code-writer 技能（CLI 工作流）或 svelte-core-bestpractices 技能（Svelte 5 runes 规则）。
• 配置 svelte-file-editor 子 Agent，以便在单独的上下文窗口中处理 .svelte / .svelte.ts / .svelte.js 文件。

如果只是纯粹询问 Svelte 5 语法，且不涉及 AI 工具，请跳过此技能，改用 svelte 技能。

---

重要：Svelte AI 概览

Svelte 团队提供了四种可协同或单独使用的 AI 工具：

工具	用途
Instructions	始终注入 Agent 会话的一小段提示词，让 Agent 了解可用工具
MCP 服务（@sveltejs/mcp）	提供工具、提示词和资源，用于从 svelte.dev 获取文档并对生成的代码进行静态分析
Skills	按需加载的指令（如 svelte-code-writer、svelte-core-bestpractices），教 Agent 使用 @sveltejs/mcp CLI 和 Svelte 5 最佳实践
Subagents	专注型 Agent（svelte-file-editor），在单独的上下文窗口中执行原子操作

快速理解：

• MCP 服务 = 基于协议的实时访问（工具在你的会话中运行）。
• Skills = Agent 按需读取的静态 Markdown。
• Subagents = 拥有隔离上下文的委派工作者。
• CLI = 与 MCP 服务使用同一引擎，但由你的 shell 驱动。

---

重要：AGENTS.md 标准

将此区块添加到 AGENTS.md（或 CLAUDE.md / GEMINI.md），让 Agent 了解有哪些 MCP 工具以及何时调用它们。运行 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 服务有两种形式：

变体	命令 / 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	设置 → 连接器 → 添加自定义连接器 → 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	仓库设置 → Copilot → Coding agent → MCP 配置中设置 "type": "http"

插件 / 市场安装（在可用时推荐）：

• 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 服务提供四种工具：

list-sections

返回包含所有文档章节的结构化列表：{ title, use_cases, path }。在任何 Svelte 对话中都应首先调用它，以便 Agent 知道要获取哪些内容。

get-documentation

接受一个或多个章节路径（逗号分隔或数组）。调用 list-sections 后，分析 use_cases 字符串，仅获取实际相关的章节——获取过多内容会浪费 token。

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 展平后的版本。适合预先添加特定知识，而无需让大模型自行获取（例如，已知任务需要用到 transitions 时，附上 svelte://transition.md）。

---

重要：MCP 提示词

svelte-task

每当需要 Agent 构建 Svelte 组件或模块时，都将此提示词作为用户消息发送。它包含：

• 可用文档章节列表（因此 Agent 无需再次调用 list-sections）。
• 一条严格规则：编写的每个 Svelte 组件 / 模块都必须经过 svelte-autofixer 修复循环，直到不再存在任何问题。
• 关于 playground-link 的规则——仅在用户确认且未写入文件时使用；playground 的入口必须是 App.svelte。

选取此提示词，将用户请求填入 <task> 占位符，然后提交。

重要：CLI 子命令

@sveltejs/mcp 既是 MCP 服务，也是 CLI。使用子命令时，程序会直接将结果输出到 stdout，而不是通过 MCP 通信。

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>	检查代码或文件	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 }。

对包含 $ 的参数使用 Shell 引号，避免变量替换。尽可能传入文件路径。

---

重要：子 Agent

svelte-file-editor

随包提供的子 Agent。生命周期：

1. 通过 list-sections → get-documentation 收集上下文。
2. 阅读目标 .svelte / .svelte.ts / .svelte.js 文件。
3. 遵循 Svelte 5 最佳实践进行编辑。
4. 调用 svelte-autofixer 验证——修复 → 重新验证，循环往复。
5. 返回更改摘要、autofixer 的检查结果和建议。

如果没有 MCP 工具，则回退到 svelte-code-writer skill；如果也没有该 skill，则回退到直接运行 npx @sveltejs/mcp@latest -y --help。

svelte-code-writer（skill）

纯 CLI 工作流。当 MCP 工具不可用时，创建 / 编辑 / 分析任何 .svelte、.svelte.ts 或 .svelte.js 文件，都必须加载此 skill。 工作流：

1. 不确定语法？使用 list-sections → get-documentation。
2. 审查 / 调试？对代码运行 svelte-autofixer。
3. 定稿前始终进行验证。

svelte-core-bestpractices（skill）

Svelte 5 惯用写法。在收到编写 / 编辑 / 分析组件的请求时，为每个 Svelte 项目加载此 skill。涵盖 $state、$derived、$effect、$props、$inspect.trace、事件、片段、{#each} 键、CSS 变量、子组件样式、上下文、Svelte 异步功能，以及应避免使用的旧版功能。

---

快速修复

• Agent 不调用 autofixer：确保仓库根目录存在 AGENTS.md，且其中包含上述约定。
• $ 展开导致 Shell 中的内联代码出错：向 svelte-autofixer 传入文件路径，而不是粘贴源代码；也可以将 $ 转义为 \$。
• get-documentation 返回内容过多 / 消耗太多 token：仅保留与 use_cases 字符串匹配的章节路径。
• Codex CLI 远程模式失败：config.toml 中缺少 experimental_use_rmcp_client = true（HTTP MCP 必需）。
• Zed：优先安装官方 Svelte MCP Server 扩展，而不是手动配置 JSON。
• Cursor CLI：目前尚不支持插件；使用桌面应用运行 /add-plugin svelte。
• GitHub Coding Agent：仅支持远程 MCP URL；该环境不提供 stdio 变体。
• Antigravity CLI：MCP 配置位于 ~/.gemini/config/mcp_config.json，而不是 ~/.config/。

---

注意事项

• playground-link 工具会创建一个在链接中编码整个项目的 URL — 链接可能很长，不应记录到错误跟踪器中。
• get-documentation 会消耗大量令牌；只获取与任务匹配的章节。切勿重新获取整个目录。
• $derived 是表达式，不是函数。需要函数体时，请使用 $derived.by(() => …)。
• Effects 不会在服务器上运行 — 切勿用 if (browser) { ... } 包裹其函数体。
• 异步 Svelte（await 表达式、可水合）要求 Svelte 5.36+ 并且在 svelte.config.js 中设置 experimental.async: true。
• 自动修复器会将大型且从不修改的对象上的 $state 视为性能隐患 — 对 API 响应请使用 $state.raw(...)。
• 每个块的键都必须唯一标识对应项 — 切勿使用循环索引作为键。
• 优先使用带键的 {#each} 块。自动修复器会指出未带键的列表。
• 在组件顶层声明的片段可以在 <script> 中引用；如果不引用组件状态，甚至可以从 <script module> 导出。
• 子 Agent（svelte-file-editor）会使用单独的上下文窗口 — 将大型编辑任务委派给它们，以缩小主 Agent 的上下文。

---

常见问题

问：AGENTS.md、CLAUDE.md 和 GEMINI.md 有什么区别？ 答：概念相同。AGENTS.md 是跨工具标准（agents.md）。Claude Code 读取 CLAUDE.md，Gemini CLI 读取 GEMINI.md。Svelte 契约在这三者中的工作方式完全相同。

问：本地 MCP 和远程 MCP，该选哪个？ 答：离线使用 / CI / 固定版本时选本地 MCP。需要始终最新的文档且不想安装时选远程 MCP。两者提供相同的工具；无需修改代码。

问：为什么我的 Agent 会跳过 svelte-autofixer？ 答：要么该工具未在 MCP 客户端中注册（重新运行安装命令），要么缺少 AGENTS.md。Codex CLI 用户：请确保 experimental_use_rmcp_client = true。

问：我可以对文件路径运行自动修复器吗？ 可以 — npx -y @sveltejs/mcp svelte-autofixer src/routes/+page.svelte。

问：skill 和子 Agent 有什么区别？ 答：skill 是 Agent 按需读取的 Markdown（成本低）。子 Agent 是拥有独立上下文窗口的委派工作者（成本较高，但能保持主上下文简洁）。

问：svelte-task 接受参数吗？ 答：接受 — 提交为用户消息之前，请将提示词正文中的 <task> 占位符替换为实际任务。

问：远程 MCP URL 稳定吗？ 是的 — https://mcp.svelte.dev/mcp 是官方且始终保持最新的端点。

问：在哪里安装 svelte-file-editor 子 Agent？ 它会随 Claude Code / Codex / Copilot / OpenCode 插件自动附带。在 OpenCode 中，你也可以在 ~/.config/opencode/svelte.json 中固定其 model / temperature / top_p / maxSteps。

问：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
• 子 Agent 参考：references/subagents-reference.md
• 架构：references/overview-reference.md