# Svelte AI Infra

> Scaffold a Svelte/SvelteKit repo's AI infrastructure source files — APM config (`apm.yml`), `.apm/` agents & instructions, `.lsp.json` — pinned to a fixed `sveltejs/ai-tools` SHA, ready for the user to run `apm install`. Use when asked to enable / initialize / set up Svelte AI tooling for a project, bootstrap svelte ai infra, or wire up sveltejs/ai-tools plugin. Do NOT use when only modifying a single skill file, a single target's config, .mcp.json alone, or apm.yml content (use Read+Edit directly).

- Skill: `gn00678465/svelte-ai-infra` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add gn00678465/svelte-ai-infra`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gn00678465/svelte-ai-infra/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: gn00678465 (https://skillmd.com/u/gn00678465)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gn00678465/svelte-ai-infra

---


# svelte-ai-infra

把這個 skill 內附的 assets 安裝到「目前專案根目錄」，準備好 Svelte AI 基礎設施的**源檔**（`apm.yml`、`.apm/`、`.lsp.json`），然後將控制權交還給使用者執行 `apm install`。本 skill **不**代跑 `apm install`，也**不**驗證部署後的 `.claude/` / `.github/` / `.agents/` 結構。

上游 `sveltejs/ai-tools` plugin pin 在 [`.upstream-ref`](.upstream-ref) 指定的 commit SHA，確保部署可重現。要升級上游版本見 [references/upstream-sync.md](references/upstream-sync.md)。

## 適用 / 不適用

**適用：**
- 新開的 Svelte / SvelteKit 專案要一次性接好 AI 工具鏈
- 既有非 Svelte 專案要新增 Svelte AI infra（先看 Step 0 衝突處理）
- 想 refresh 既有專案的 `.apm/` 源檔到 pinned 上游版本

**不適用：**
- 代跑 `apm install` 或排查既有 `apm install` 錯誤（直接看錯誤訊息與 `apm.lock.yaml`）
- 只想單獨設定 `.mcp.json` 或 MCP server
- 只想更新單一 skill（`svelte-code-writer` / `svelte-core-bestpractices`）
- 只想針對 Claude 或 Copilot 其中一個 target 配置
- 修改既有 `apm.yml`（直接 `Read + Edit`）
- 想客製非 sveltejs/ai-tools 來源的 Svelte 工具鏈

## 前置條件

- `apm` CLI **≥ 0.13.0**（0.12.x 對 `targets: [claude, copilot]` 路由有 bug — 詳見 [references/version-compat.md](references/version-compat.md)）
- Bash 環境（Linux / macOS / Windows Git Bash）
- 可上網（無網時 fallback 到內附版本）

## 流程速覽

按順序執行 Step 0 → 3。每步驟末「驗證」必須通過才進下一步。Step 3 把控制權交還給使用者。完整指令、placeholder 清單與驗收條件見 [references/workflow.md](references/workflow.md)。

| Step | 動作 | 詳細 |
|---|---|---|
| 0 | Preflight 衝突檢測 | [workflow.md § Step 0](references/workflow.md#step-0--preflight檢測既有檔案決定覆寫策略) |
| 1 | 複製 assets + 替換 4 個 placeholder | [workflow.md § Step 1](references/workflow.md#step-1--複製-assets-到專案根目錄--替換-4-個-placeholder) |
| 2 | Refresh `.apm/` 源檔（pinned SHA）+ frontmatter + 驗證 `.apm/` 正確 | [workflow.md § Step 2](references/workflow.md#step-2--refresh-apm-源檔pinned-sha-規範化-frontmatter--驗證) |
| 3 | 把控制權交還使用者，提示執行 `apm install` | [workflow.md § Step 3](references/workflow.md#step-3--把控制權交還使用者) |

## SKILL_ROOT 解析

各 step 引用 `$SKILL_ROOT` — skill 在當前環境的實際安裝路徑。**不要硬編** `.claude/skills/svelte-ai-infra`，因為這份 skill 同時可能透過 plugin marketplace 安裝、或在開發中從本 repo 直接執行。請依當前環境暴露的實際路徑為準：

- **Claude Code 安裝**：通常在 `$CLAUDE_PLUGIN_ROOT/skills/svelte-ai-infra`，若有此環境變數請優先使用
- **本 repo 開發**：`plugins/frontend-dev/svelte-ai-infra/skills/svelte-ai-infra`
- **fallback**：先試 `.claude/skills/svelte-ai-infra`，若不存在就由 caller 顯式傳入

Step 1–2 開頭：
```bash
SKILL_ROOT="<實際安裝路徑>"
```

## Output Format

完成後請在最後回報 4 項：

1. **Fetch 結果**：兩個源檔分別是 `fetched`（取得 pinned SHA 版本）或 `fallback`（使用內附版本）
2. **`apm.yml` 佔位替換**：4 個（3 個 `<...>` + 1 個 `__UPSTREAM_SHA__`）是否都已替換
3. **Skill scope 驗證**：4 項各報 `OK` 或 `FAIL`
   - `apm.yml`（4 個 placeholder 全部替換）
   - `.apm/agents/svelte-file-editor.agent.md`（存在 + 內容含 `Svelte MCP server`）
   - `.apm/instructions/svelte-mcp-tools.instructions.md`（存在 + frontmatter 有正確 `applyTo` / `description`）
   - `.lsp.json`（存在）
4. **交還指令**：明確列出使用者接下來要跑的指令（`apm install` 或 Windows 的 `apm.cmd install`），以及預期會產生的 artifact（`apm.lock.yaml`、`.claude/` / `.github/` / `.agents/` 結構、`.mcp.json` 的 `svelte` server）

## 升級上游 plugin 版本

詳見 [references/upstream-sync.md](references/upstream-sync.md)。

## 疑難排解 / 已知陷阱

詳見 [references/troubleshooting.md](references/troubleshooting.md)。