docs(mcp): CLAUDE.md 与 cocos-mcp 技能只保留 MCP 自身给不了的信息

原文档写着"164 个工具"并复述了一份按前缀分的工具清单, 对应的是已删除的旧扩展,
照着写会调不到工具。

改为不再复述工具用法: cocos-mcp-server 连上后会自注入 5.5K 字符的完整说明
(CRITICAL RULES + intent→tool 速查表 + 批量操作), 16 个工具的 description 也
各带 action 枚举与示例, 仓库里再维护一份副本必然随扩展版本腐化。

文档只保留 MCP 给不了的部分——服务离线时它的自带说明也一并消失, 而那正是最需要
"去编辑器点 Start Server"和"不要转而手改序列化文件"的时刻:
- 前置条件、curl /health 探活、连不上时的排查顺序
- settings/mcp-server.json 的 autoStart:false, ECONNREFUSED 的常见成因
- 已知坑: cocos_asset.search 的 type 过滤失效; cocos_scene.hierarchy 的
  includeComponents 失效; 编辑器里的 scene-2d 是 Creator 内置模板而非工程资产
  (assets/ 下 0 个 .scene), 不必去仓库里找

技能里原本重复的"禁止手改 .scene/.prefab"规则改为引用 CLAUDE.md 单一来源, 依据
是仓库第二准则; 基线测试也表明未读该技能的 agent 仅凭 CLAUDE.md 即拒绝手改。

CLAUDE.md 里"动手前先读技能"改为条件式(正常操作不必读, 故障时才读), 此前该指令
与技能的排障定位冲突, 实测中不同 agent 对它的解读并不一致。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.claude/skills/cocos-mcp/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: cocos-mcp
+description: Use when 要对 YouleNexus 工程做任何 Cocos Creator 编辑器操作（场景/节点/组件/prefab/资源/动画/预览截图），或 cocos_* 工具压根没出现、调用报连接失败、curl 127.0.0.1:3000 不通时。
+---
+
+# cocos-creator-mcp 接入与排障
+
+工程 `cocoscreator_projects/YouleNexus`。编辑器操作走 `mcp__cocos-creator-mcp__cocos_*` 工具。
+
+「禁止手改 `.scene`/`.prefab`/`.anim`/`.meta`」这条规则的唯一来源是 CLAUDE.md，本文件不复述——按仓库第二准则，同一条规则不在两处定义。
+
+## 工具怎么用：不在本文件
+
+MCP server 连上后会自动注入完整说明（CRITICAL RULES + intent→tool 速查表 + 批量操作），每个工具的 description 也带 action 枚举和示例。**照它的说明用，不要在本文件重复维护一份工具清单**——扩展换版本时那份副本必然过期误导。
+
+当前扩展 `cocos-mcp-server`（`extensions/cocos-mcp-server/`），暴露 16 个聚合工具（`cocos_scene` / `node` / `component` / `prefab` / `asset` / `editor` / `view` / `composite` / `knowledge` / `validate` / `template` / `capture` / `builder` / `animation` / `spine` / `label`），每个靠 `action` 参数分派。工具默认是 deferred，先 `ToolSearch` 加载 schema 再调。
+
+## 前置条件（缺一不可）
+
+1. Cocos Creator 3.7+ 已打开 `YouleNexus` 工程；
+2. 扩展 **Cocos MCP Server** 已启用，且在其面板里点了 **Start Server**（监听 `http://127.0.0.1:3000/mcp`）。
+
+Claude Code 侧配置在仓库根 `.mcp.json`，HTTP 直连，服务器名 `cocos-creator-mcp`（改名会同时打断 `.claude/settings.local.json` 里的 `mcp__cocos-creator-mcp__*` 允许规则）。
+
+## 探活
+
+```bash
+curl http://127.0.0.1:3000/health
+# 期望：{"status":"ok","tools":16,"transport":"streamable-http"}
+```
+
+## 连不上时
+
+**提示用户去编辑器里启动服务，不要盲目重试，更不要绕开 MCP 去手改序列化文件。** 服务只在编辑器进程内，外部无法代为启动。
+
+按此顺序排查：编辑器是否开着 → 扩展是否启用 → 面板是否点过 Start Server → `/health` 是否通 → `.mcp.json` 是否仍指向 `http://127.0.0.1:3000/mcp`（历史上曾指向已删除的 stdio-bridge 路径）。改完 `.mcp.json` 需重启会话才生效。
+
+`settings/mcp-server.json` 里 `autoStart: false`，所以每次开编辑器都得手动点 Start Server；这大概率就是 `ECONNREFUSED` 的常见成因（改 true 应可自动启动，**未实测**）。
+
+## 已知坑
+
+- `cocos_asset{action:"search"}` 的 `type` 过滤**不生效**：传 `cc.SceneAsset` 照样返回脚本和目录，返回消息还谎称「of type 'cc.SceneAsset'」。自己按结果里的 `type` 字段过滤。
+- `cocos_scene{action:"hierarchy"}` 的 `includeComponents: true` **不生效**，返回树里没有组件信息。要拿组件得对每个节点追加 `cocos_node{action:"info"}`。
+- 工程当前**没有任何场景资源**（`assets/` 下 0 个 `.scene`，只有 `framework/` 的 `.ts`）。编辑器里那个 `scene-2d` 是 Creator 内置模板（`db://internal/default_file_content/scene/scene-2d.scene`）新建出来的未保存场景，不是工程资产——别浪费时间去仓库里找它。
+- 安装方式与历史沿革记在项目记忆 `cocos-creator-mcp-setup`。

CLAUDE.md

@@ -78,14 +78,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Cocos Creator 新前端：优先使用 cocos-creator-mcp
 
-新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**（场景、节点、组件、prefab、资源、预览/截图/录制等），都应**优先使用 `cocos-creator-mcp` 这组 MCP 工具**（命名空间 `mcp__cocos-creator-mcp__*`，共 164 个）直接驱动编辑器，而不是手改 `.scene` / `.prefab` / `.meta` 等序列化文件——手改极易破坏 UUID 引用与序列化结构。
+新工程 `cocoscreator_projects/YouleNexus`。**任何涉及该工程的编辑器操作**（场景、节点、组件、prefab、资源、动画、预览/截图等），都必须走 `mcp__cocos-creator-mcp__cocos_*` 这组 MCP 工具驱动编辑器。
 
-**前置条件（缺一不可，否则工具调用必然失败）：**
+**绝不允许手改** `.scene` / `.prefab` / `.anim` / `.meta`——它们是 UUID 引用的序列化资源，任何文本编辑都会破坏引用结构，导致「资源导入失败」且只能人工恢复。**MCP 连不上时也不例外**：应提示用户去编辑器启动服务，而不是退而求其次去手改文件。
-1. Cocos Creator 3.8+ 已打开 `YouleNexus` 工程；
-2. 扩展 `cocos-creator-mcp` 已启用，并在其面板里点了 **Start Server**（监听 `http://127.0.0.1:3000/mcp`）。
 
-**开工前先探活**：先调用 `mcp__cocos-creator-mcp__server_get_status`（或 `curl http://127.0.0.1:3000/health`，期望 `{"status":"ok","tools":164}`）。**连不上时，提示用户在编辑器里启动服务，不要盲目重试**——MCP 桥（`extensions/cocos-creator-mcp/client/stdio-bridge.js`）只转发，无法替你启动编辑器服务。
+具体工具用法不写在这里——MCP server 连上后会自注入完整说明（工具清单、action 速查、批量操作），以其为准，**正常操作不需要先读任何仓库文档**。
 
-**工具分类（按前缀）：** `scene_*`（场景生命周期/层级/查询/撤销）、`node_*`（增删改/变换/树）、`component_*`、`prefab_*`、`asset_*`、`project_*`、`builder_*`（预览/构建）、`debug_*`（截图、录制、game command、控制台日志）、`view_*`（gizmo/相机/网格）、`refimage_*`、`preferences_*`、`server_*`。
+`cocos-mcp` 技能（`.claude/skills/cocos-mcp/SKILL.md`）只记录 MCP 自己给不了的部分：前置条件、探活、排障、已知坑。**工具正常时不必读它；一旦 `cocos_*` 工具没出现、调用报连接失败、或行为与预期不符，就去读。**
-
-> MCP 的项目级安装方式与排障细节（扩展位置、`package.json` name 必须为 `cocos-creator-mcp`、镜像 404 等坑）记录在项目记忆 `cocos-creator-mcp-setup`。