用途
本技能是 Cocos Creator 跨平台 2D/3D 游戏引擎开发助手，作为入口与路由：核心工作流与速查表放在主文件，深度内容按需从 references/ 加载，避免一次性占满上下文。
适用场景包括：
- 编写、重构、调试 Cocos Creator 的 TypeScript / JavaScript 组件脚本
- 解释 cc 模块 API、节点与组件体系、生命周期、事件、动画、物理、UI、资源与场景管理
- 排查构建与发布问题：微信小游戏、抖音小游戏、H5、iOS、Android、HarmonyOS Next
- 性能优化：DrawCall、合批、内存、对象池、包体与首屏加载
- 3.x → COCOS 4 的 API 迁移与版本兼容判断
不适用：Unity / Unreal / Godot / Cocos2d-x C++ 的问题（API 不通用）；纯美术与策划数值设计。
使用方式
第 0 步：先确认版本再写代码，这一步不能跳过。3.x 与 2.x API 不兼容，3.8 与 COCOS 4 之间也存在差异。可读取 project.json 或查找根目录及二级目录中带 "cc" 字段的 package.json 来确认版本；拿到版本后按对应 API 写代码，并在回复中注明版本。拿不到版本时先询问用户，或明确声明所用版本及需改写的前提。版本状态：2.x 已停止演进，保留 cc.Class、cc.Node 老 API；3.8.x 为长期主力稳定版，3.8.9 是 2026 年最新补丁，3.8.5+ 支持 HarmonyOS Next；COCOS 4 于 2026 年 1 月 MIT 全开源，是 3.x 的演进版，承诺前向兼容，编辑器能力逐步迁往 Headless CLI。
第 1 步：定位代码该写在哪。先读项目现有结构再动手，典型约定：assets/ 下含 scenes/、scripts/（components、managers、utils）、prefabs/、textures/、audio/、animations/、materials/、resources/。三个硬约束：新增资源必须让编辑器生成同名 .meta，否则引用丢失、构建报错；只有 assets/resources/ 下资源能用 resources.load() 按路径加载，其他目录须通过 @property 挂引用；脚本与组件类映射由 .meta 中 UUID 决定，勿重命名或移动已被场景引用的脚本。
第 2 步：写代码。组件骨架基于 3.8.x，使用 import { _decorator, Component, Node, Vec3 } from 'cc' 与 @ccclass/@property 装饰器，覆盖 onLoad、start、update、lateUpdate、onEnable/onDisable、onDestroy 等生命周期回调。
第 3 步：必须验证。可选最低成本方式：npx tsc --noEmit -p tsconfig.json 做类型检查；python skills/cocos-creator/scripts/cocos_doctor.py --project . 做项目体检（检查 .meta 缺失、脚本断链、resources 误放、大文件）；或编辑器预览 / CLI 构建（COCOS 4 的 cocos-cli 支持 Headless 构建）。验证未跑通须如实说明。
第 4 步：提交前自查常见陷阱，包括 Node.position 引用语义、resources.load 路径不带扩展名、事件 on/off 成对且 target 一致、instantiate 后必须 addChild、频繁实例化用对象池、图集与材质是合批前提、异步竞态需 isValid 防护。
主要能力与参考资源
按需加载的参考文件：api-quick-ref.md（常用模块导入与 API 速查）、examples.md（玩家控制器、对象池、UI 列表、状态机等完整示例）、best-practices.md（项目架构、目录约定、单例与事件总线、代码规范、资源管理）、performance.md（DrawCall、合批、内存、GC、包体、首屏加载优化路径）、publishing.md（微信/抖音小游戏分包，H5、iOS、Android、HarmonyOS Next 发布清单）、troubleshooting.md（编辑器、脚本编译、资源、物理、UI、构建发布排查手册）、cocos4-migration.md（3.8 → COCOS 4 迁移、cocos-cli / Headless、AI-Native 能力变化）。
限制
本技能由社区维护，与官方文档不一致之处以官方文档为准。不覆盖 Unity / Unreal / Godot / Cocos2d-x C++。危险信号提示包括版本混杂、resources 路径误用、.meta 缺失、改被引用脚本名后断链、destroy 后访问节点、未提供量化数据即称已优化等，出现时应先停下确认。