内置工具

应用把高频能力打包成「内置 Skill」，随安装包一起发布：每个 Skill 是一个目录，含一份SKILL.md（YAML frontmatter + Markdown 正文）、一个声明 id 与依赖工具的manifest.json，需要时还会带references/、scripts/、 templates/、data/。本页按真实目录逐个列出当前内置的全部 17 个 Skill，并给出各自真实的 id、版本、分类、配套工具与踩坑点。

目录位置：开发态apps/desktop/resources/skills/，打包后 process.resourcesPath/skills；只读，随应用升级更新。

1. 内置 Skill 怎么生效

1. 进库：每次技能列表被请求时会重新扫描内置目录（ensureBuiltInSkills()）， 按manifest.json里的id（形如builtin:<目录名>）写入 / 更新skills表，scope=system。改完文件不用手动同步。
2. 分配给 Agent：技能靠 Agent 配置里的skillIds 生效。到左侧「Agent」页编辑 目标 Agent，在 Skills 一栏点「管理 Skills」勾选；被列入 disabledSkillIds的则从该 Agent 的可用集里剔除。新装技能后应用会弹「技能已就绪，是否现在分配给 Agent」的提示，就是因为 这一步不做的话技能不会自动参与对话。
3. 进上下文的是目录：system prompt 里只有id + 名称 + 截断描述， 并提示 Agent「需要时用mcp__spark_platform__skills_load取完整指令」。 这就是渐进式披露：17 个技能全开也只占一份目录的体积，正文按需加载。
4. 手动点名：会话输入框的「+ → 技能」菜单会列出可用技能（含当前工作区扫描到的 项目级技能），点击把@技能名插入输入框，用来在单轮里显式指定要用哪个技能。
5. 启用 / 停用与删除：内置技能不能删除（删除接口明确拒绝builtin:前缀），只能通过skills_toggle（或界面开关）把enabled置 0 停用。

2. 17 个内置 Skill 总览

Skill id	名称	分类	版本	一句话定位
builtin:claude-api	claude-api	utility	—（frontmatter 未给版本）	Claude API / Anthropic SDK 应用的构建、调试、迁移与 prompt caching
builtin:commit	commit	coding	1.0.0	分析变更并生成 Conventional Commits 提交信息
builtin:react	react	utility	—	@lobehub/ui + antd-style 技术栈的 React 组件与路由约定
builtin:frontend-design	frontend-design	utility	—	先定美学方向再写代码，避免通用 AI 审美
builtin:skill-creator	skill-creator	utility	—	创建 / 改进 Skill：评测、基准、触发描述优化
builtin:spark-workflow-generator	spark-workflow-generator	utility	0.2.0	从自然语言生成可导入的 WorkflowGraph JSON（13 种节点）
builtin:multi-search-engine	multi-search-engine	utility	2.1.0	用内置spark_search检索网页并给出有出处的答案
builtin:browser-use	browser-use	utility	1.0.0	用 Playwright MCP 的 snapshot + ref 操作真实浏览器
builtin:canvas-studio	画布工作室	utility	1.7.0	用spark_canvas工具操作无限画布与影视流水线
builtin:multimedia-use	多媒体使用	utility	1.0.0	图片 / 视频 / 音频的生成、编辑与转写路由
builtin:video-workflow	video-workflow	utility	1.0.0	纯本地 ffmpeg 视频处理（抽帧 / 转码 / 剪辑 / 字幕）
builtin:spark-web-tool	Spark Web Tool	writing	2.1.0	课件 / 专题讲解 / 数据分析报告三类内容产物
builtin:echarts	echarts	utility	1.0.0	生成可直接使用的 ECharts 配置
builtin:ui-ux-pro-max	ui-ux-pro-max	utility	—	带 CSV 数据与检索脚本的 UI/UX 设计知识库
builtin:spark-debug	Spark Debug	debugging	1.0.0	假设驱动 + 人在回路的插桩调试闭环
builtin:find-skills	find-skills	utility	1.0.0	按任务描述搜索并推荐技能（含远程市场）
builtin:platform-manager	平台管理	utility	2.8.0	用mcp__spark_platform__*管理平台数据

表中「—」表示该SKILL.md的 frontmatter 只声明了name与 description（部分还带license），没有version/ author，入库时版本落到0.0.0。带LICENSE.txt的 （claude-api、frontend-design）是随包分发的第三方技能。

两个容易看错的字段：分类只从 frontmatter 的category读（缺省按utility入库），manifest.json里的category 不参与入库——例如react目录的 manifest 写的是coding， 但它的 frontmatter 没有category，所以入库分类是utility； 同理 manifest.json只负责提供id、requiredTools、parameters，其余元信息都来自SKILL.md。

3. 编程与工程类

3.1 claude-api

覆盖 Claude API / Anthropic SDK 应用的构建、调试与优化：prompt caching、tool use、 batch、files、citations、memory、thinking、compaction，以及把老代码迁移到当前模型、 替换已退役模型。目录里有 45 个文件、17 个子目录，按语言给出示例（python、typescript、go、java、php、ruby、csharp、curl、shared）。

• 触发：代码里 importanthropic/@anthropic-ai/sdk，或问 prompt caching 命中率、thinking、batch、Managed Agents、模型迁移。
• 跳过：代码 importopenai或其它厂商 SDK、文件名形如 *-openai.py/*-generic.py、provider-neutral 代码。
• 配套工具：无（requiredTools为空），纯说明 + 代码示例。

3.2 commit

分析git diff/git status，把变更按逻辑分组，生成 Conventional Commits 格式的提交信息：<type>(<scope>): <subject>。 type 枚举为feat、fix、refactor、style、docs、test、chore、perf、ci； subject 建议不超过 50 字符、不以句号结尾。

• 配套工具：Bash（跑 git 命令）。
• 关键约束：生成信息后必须展示给用户确认再执行提交，不会自动 commit。
• 典型提示词：「按 conventional commits 规范提交我的改动」「把这次改动拆成几个合理的 commit」。

3.3 react

面向@lobehub/ui+ antd 技术栈的 React 组件写作约定：复杂样式用antd-style、简单场景用 inlinestyle；布局优先用Flexbox /Center；组件优先级为src/components> 已安装包 > @lobehub/ui> antd； zustand 用 selector 取值。路由部分区分 Next.js App Router（登录 / 注册 / OAuth）与 react-router-dom 主 SPA（desktopRouter.config.tsx），并强调 SPA 内用Link/useNavigate而不是next/link。

• 配套文件：references/layout-kit.md；@lobehub/ui 组件清单在技能正文里。
• 注意：这些约定来自@lobehub/ui 生态（含具体文件路径），换到其它 React 技术栈时只有通用部分可参考。

3.4 frontend-design

先做设计判断、再写代码：明确用途与受众、选定一个明确的美学方向（极简 / 极大主义 / 复古未来 / 编辑风 / 工业风等）、再落到字体、色彩、动效、空间构图与背景质感。 明确禁止通用 AI 审美——不用 Inter / Roboto / Arial 之类默认字体，不用「白底紫渐变」， 也不要每次都收敛到同一套选择。

• 典型场景：「做一个有质感的 SaaS landing page」「把这个 dashboard 做得不那么 AI 味」。
• 配套工具：无。产出是可运行的 HTML/CSS/JS 或 React 代码，写文件靠宿主 Agent 自身能力。

3.5 skill-creator

创建和改进 Skill 的完整工作流：捕获意图 → 访谈补齐输入 / 输出格式与边界 → 写草稿 → 造测试 prompt → 生成量化 eval → 用评测脚本看结果 → 按反馈重写 → 扩大测试集； 最后还有专门的 description 优化步骤，用于提升技能触发的准确率。

• 配套文件：19 个文件（含eval-viewer/generate_review.py 之类的评测脚本与模板）。
• 典型提示词：「帮我创建一个sql-explain 技能」「我的技能总在错误的场景被触发，帮我改 description」。

3.6 spark-workflow-generator

把自然语言需求编译成 Spark 可导入的WorkflowGraphJSON，节点种类是封闭枚举的 13 种：input、plan、route、 agent、subagent、skill、tool、 mcp、approval、verify、review、 artifact、loop。产物是「待审草案 + 校验报告」， 需要人工确认后才导入。

• 配套文件：references/schema-freeze.md（schema 与 preflight 错误码）、references/node-spec.md（13 种节点规格）、4 个模板（线性 / 条件路由 / 迭代循环 / 审批+MCP）、demos/示例。
• 离线校验：生成后先跑 node scripts/validate.mjs <生成的.json>，错误码与导入前的 preflight 对齐。
• 硬性规则：绑定类字段（agentId/skillIds/ toolIds/mcpServerIds/ruleIds/ modelId/providerProfileId/toolServerId）必须留空，跨环境写死必然失效；坐标x/y在节点顶层而不在 config里；分支条件必须互斥且各自独立收尾，不能汇合；loop不嵌套、maxIterations ≤ 50；每张图恰有一个input起点、每条链以 artifact收尾。
• 分工：实时操作当前画布请用canvas-studio，视频转码剪辑请用 video-workflow，本技能只负责生成 / 修改工作流定义 JSON。

4. 联网与浏览器类

4.1 multi-search-engine

用内置spark_searchMCP 的web_search/fetch_url 检索网络并抓取正文，综合多来源给出带出处的答案。因为搜索在本地子进程里自己发 HTTP， 与模型供应商解耦，走第三方 OpenAI 兼容 API 时同样有效（SDK 自带的 WebSearch / WebFetch 在第三方供应商下会被剥离）。

• 配套工具：mcp__spark_search__web_search、mcp__spark_search__fetch_url（写在 manifest 的 requiredTools 里）。
• 用法与后端配置：见联网搜索（免密默认链 + keyed 后端）。
• 行为约定：按时效性判断要不要搜；优先一手权威来源；片段不够就抓正文；材料冲突要显式调和；不得把「没搜到」当成「不存在」。

4.2 browser-use

通过 Playwright MCP 驱动真实浏览器完成导航、点击、输入、截图与数据提取。核心方法论：browser_navigate之后立刻browser_snapshot拿到可访问性树， 每个可交互元素带ref编号；后续一律基于ref操作 （element="ref=3"），不要写 CSS selector；每次动作后再 snapshot 确认； 复杂视觉页面才截图辅助；收尾调browser_close释放资源。

• 配套工具（manifest 声明 7 个）：mcp__playwright__browser_navigate/snapshot/click /type/press_key/take_screenshot/ close。
• 运行参数：mode可选headful（默认，显示窗口）/ headless。
• 环境兜底：会话里没有mcp__playwright__browser_*时，先用 mcp__spark_platform__mcp_status检查内置playwrightMCP 是否被停用 （停用就让用户去启用，不要自己重启进程）；确实缺失才自行安装并注册 scope=project、type=stdio、command=npx、args=["-y","@playwright/mcp"]的 MCP。网络受限时切 registry.npmmirror.com与PLAYWRIGHT_DOWNLOAD_HOST， 且不要写进全局~/.npmrc。
• chromium 按需下载：仅当确认没有可用的系统 Chrome/Edge / Playwright 缓存时才下载，且要先告知用户约 150MB。
• 另一条路：需要应用内可见窗口、本地file://调试、console / network 观察或保留登录态时，用内置的mcp__spark_browser__*（见 浏览器自动化）。

5. 画布、多媒体与内容生产类

5.1 canvas-studio（画布工作室）

用mcp__spark_canvas__*工具直接读写当前打开的画布项目。工具清单以canvas.tools.ts注册为准（当前53 个），只有画布弹窗 attach 到当前会话时 才注入——没有画布绑定时，Agent 看不到这些工具。

• 节点类型：内容节点image/audio/ video/text/prompt/group，加上 AI 操作节点text_to_image、image_to_image、image_edit、image_compose、panorama_360、text_generate、text_rewrite、prompt_optimize、text_to_video、image_to_video、video_edit、video_extend、text_to_audio、audio_transcribe。
• 影视语义：node.data.pipelineRole表达流水线角色（style_bible/screenplay/character/ scene/shot/keyframe/clip等）；node.data.productionState走empty → drafting → draft → confirmed，上游变更后下游可标stale。
• 黄金规则：编辑前先canvas_get_project_summary；宽泛目标先 canvas_get_production_plan；针对某节点先 canvas_get_available_actions；多节点流程必须用 canvas_create_reusable_workflow_graph 原子创建（不要拼低层创建后漏连线）；只操作当前画布，不创建 / 切换多画板；破坏性操作先问用户；保存工作流是独立动作（canvas_workflow_extract_selection），不会自动落库。
• 常见坑：画布工具必须由主 Agent 直接调用，不要委派给子 Agent（子 Agent 没有 attach 上下文）；工具返回「无输出」不等于画布断连，先读回验证再决定是否重试；参数字段不确定时用 canvas_describe_tool取精确 schema。

5.2 multimedia-use（多媒体使用）

把创作意图翻译成可执行的图片 / 视频 / 音频任务。覆盖文生图、图生图、图片编辑与局部重绘、 多图合成、文生视频、图生视频、首尾帧视频、视频编辑与扩展、TTS / 配音、音频转写， 以及模型能力与参数约束的查询。

• 画布会话：优先用mcp__spark_canvas__*——canvas_list_media_models选模型 →canvas_create_operation_node 建可检查的操作节点 → 用户明确要求立即执行时才canvas_run_operation→ canvas_list_tasks跟进。
• 普通会话：用mcp__spark_media__*——先list_models，再describe_model看参数 schema，最后调generate_image/ edit_image/generate_video/generate_audio/ transcribe_audio；异步任务用get_task/cancel_task；Provider 文件用upload_file/get_file/list_files /delete_file（删除前必须确认）。
• 常见坑：不得静默改用默认模型——用户指定模型时要原样传 list_models返回的selectionKey；不要把适配器模板里的模型 ID 当成真实模型 ID；工具没注入时如实说明，不要假装已生成。

5.3 video-workflow

纯本地 ffmpeg 处理，不经过大模型：关键帧提取（场景突变 / I 帧 / 均匀采样）、转码、 剪辑、合并、变速、倒放、裁剪、加水印、烧字幕、生成 GIF、分割视频。

• 配套工具：Bash（调ffmpeg/ffprobe）。
• 前置检查：每次处理前先ffmpeg -version/ ffprobe -version；不可用时不要自行安装，引导用户到「设置 → 完整性 → 视频处理 (FFmpeg) → 下载 FFmpeg」。
• 路径线索：Spark 管理的 ffmpeg 落在应用 userData 的 bin/<版本>/下（macOS 形如 ~/Library/Application Support/spark-desktop/bin/<版本>/ffmpeg）。
• 流程约定：先ffprobe探明时长 / 分辨率 / 编码再决定参数；产物文件名带操作语义放在工作目录；长任务告知预计耗时。

5.4 spark-web-tool

三类内容产物，全部先过一遍澄清再动手：

1. 交互式课件（courseware）：澄清 → 大纲确认 → 内容脚本 → 产物生成，输出 PPTX / HTML / DOCX / Markdown。
2. 专题讲解（explain）：澄清 → 理解 → 研究 → 验证 → 脚本 → 产物生成，输出 HTML 幻灯片 / 自定义网页 / PPTX / DOCX。
3. 数据分析（data-analysis）：读 CSV / Excel → 分析 → 产出带图表的 HTML 报告。

• 澄清协议：Stage 0 会生成 7~12 个问题，覆盖「内容」「设计方向」「视觉细节」三组，配色题给色板选项、版式题给预览；用户已经说过的信息不重复问。
• 配套工具：Read、Write、Bash、mcp__spark_search__web_search、mcp__spark_search__fetch_url。
• 参数：taskType、outputFormats、style、includeQuiz、dataFileName、dataFileUrl、chartTypes、designSystem。
• 配套文件：33 个文件，references/下按clarify/ courseware/explain/data-analysis/ snippets分目录，另有README.md。
• 典型提示词：「做一份《光合作用》的交互式课件」「把这份 CSV 变成数据报告」「讲解一下快速排序，要能互动的网页」。

5.5 echarts

生成可直接使用的 ECharts 配置：按数据特征选图型（趋势 → 折线 / 面积，占比 → 饼 / 环形， 分布 → 散点 / 气泡，多维 → 雷达，层级 → 矩形树图 / 旭日图，流向 → 桑基 / 漏斗， 时序 → K 线，地理 → 地图 / 热力，关系 → 关系图），并带上默认样式约定。

• 默认样式：色板 ['#5470c6','#91cc75','#fac858','#ee6666','#73c0de','#3ba272','#fc8452','#9a60b4','#ea7ccc']；开tooltip、legend，grid留白 top 60 / right 40 / bottom 40 / left 60；配 resize 监听。
• 组合用法：可以单独使用，也可以作为spark-web-tool 数据分析报告里的图表子任务。

6. UI / 设计类

6.1 ui-ux-pro-max

一个带数据的本地设计知识库：data/*.csv存知识，scripts/search.py做 BM25 检索，scripts/design_system.py 生成成套设计系统建议。 技能自述的规模是「50+ 风格 / 161 色板 / 57 字体配对 / 161 产品类型 / 99 UX 准则 / 25 图表 / 10 技术栈」， 按随包数据的实际行数核对如下：

数据文件	行数	对应能力
data/colors.csv	161	按产品类型选的完整色板（primary / accent / border / ring 等）
data/products.csv	161	产品类型 → 设计模式
data/styles.csv	84	UI 风格库（glassmorphism、brutalism、bento grid 等）
data/typography.csv	73	字体配对推荐
data/ux-guidelines.csv	99	UX 准则（含 Do / Don't 与代码示例）
data/charts.csv	25	图表类型选择建议
data/icons.csv	105	图标使用建议
data/react-performance.csv	44	React 渲染性能准则
data/stacks/react-native.csv	—	技术栈专属数据（--stack目前只有react-native一项）

检索脚本的真实用法（在技能目录下执行）：

# 生成成套设计系统建议
python3 scripts/search.py "<产品类型> <行业> <关键词>" --design-system -p "项目名"

# 落盘到 design-system/MASTER.md（可再为单页生成覆盖文件）
python3 scripts/search.py "<关键词>" --design-system --persist -p "项目名" --page "dashboard"

# 按域查询明细
python3 scripts/search.py "<关键词>" --domain <domain> -n 5

# 技术栈专属查询（当前仅 react-native）
python3 scripts/search.py "<关键词>" --stack react-native

• 可用 domain（脚本的真实可选值）：style、color、chart、landing、product、ux、typography、icons、react、web、google-fonts。
• 输出控制：--format ascii|markdown、--json、--output-dir。
• 注意：仓库里scripts/search.py的--help 文案仍写着html-tailwind / react / nextjs，但STACK_CONFIG 实际只实现了react-native；其它栈请用--domain查询。

7. 调试与平台管理类

7.1 spark-debug

「假设驱动 + 人在回路」的调试闭环。核心原则是Agent 不复现 bug： 它负责假设、插桩、读日志、修复、清理，用户负责操作复现；每插一轮桩就结束 turn 把控制权交回用户。

• 挂载条件：不是常驻技能。会话里打开「调试模式」开关（per-session，不继承全局偏好）后，运行时才挂载 mcp__spark_debug__*并注入状态机提示词。
• 工具：begin（拿 sid / 端口 / 轮次与插桩上报器）、read（拉本轮日志）、status（看本轮条数与假设台账）、next_round（推进轮次）、finish（清空日志并返回待删除的插桩标记）。
• 参数：bugDescription（必填，现象 + 复现步骤 + 期望 vs 实际）、targetRuntime（browser默认 /node/ other，决定用哪套语言的上报器模板）。
• 插桩规范：日志块必须用 // __SPARK_DEBUG_START__ ... // __SPARK_DEBUG_END__包裹；status.thisRound === 0时不要硬分析空日志，改插桩点或复现步骤。
• 护栏：约 6 轮仍未定位就收口总结；交付的硬条件是finish后全仓 grep__SPARK_DEBUG零残留；报告中还要说明日志证据。

7.2 find-skills

技能发现与推荐：解析任务需要什么能力（编码 / 设计 / 搜索 / 数据处理）与技术栈，用 mcp__spark_platform__skills_search搜远程技能库，再结合已安装列表给出推荐， 每条说明「匹配原因 / 如何使用 / 来源是已安装还是需要安装」。推荐策略偏保守： 基础编程任务不额外推荐、用户已指定工具时不推替代品、优先已安装的技能， 并在需要多种能力时给组合（如前端页面 →frontend-design+react）。

7.3 platform-manager（平台管理）

用mcp__spark_platform__*管理应用内的平台数据（本机 SQLite + JSON 文件， 不是全局 Claude 配置）。工具清单以packages/agent-runtime/src/tools/platform-management-mcp-server.mjs注册为准， 当前共124 个（技能正文里写的「94 个」是历史值），分组如下：

分组	数量	代表工具
Skills	8	skills_list/skills_load/skills_install_github /skills_toggle
MCP	5	mcp_list/mcp_create/mcp_update/ mcp_delete/mcp_status
自定义工具	11	custom_tools_guide/custom_tools_validate/ custom_tools_test/custom_tools_publish
工具包（Tool Package）	22	tool_packages_create_project/tool_packages_install_git/ tool_packages_test
Providers	13	providers_list/providers_health_check/ providers_media_configure
Workflows	5	workflows_list/workflows_create/ workflows_update
Agents	5	agents_list/agents_create/agents_update
Teams	5	teams_list/teams_create/teams_update
看板任务	10	board_list/board_create/board_batch_update/ board_restore
GitHub	15	github_status/github_create_branch/ github_create_pull_request
会话	6	sessions_get/sessions_switch_model/ sessions_switch_permission
会话定时任务	5	session_schedule_create/session_schedule_delete
会话历史	3	session_history_list/session_history_search/ session_history_read
参考会话	3	referenced_sessions_list/referenced_session_search
Artifacts	2	artifacts_list/artifacts_resolve
Codex 运行时	2	codex_runtime_diagnostics/codex_runtime_restart_idle
设置	4	settings_get/settings_set/settings_get_all

破坏性操作（删除、卸载、发布、启用）在工具描述里都要求先向用户确认； Agent 侧只管平台数据，不替代画布 UI 操作。详见Agent 工作流 / Platform 管理工具。

8. 按任务挑选

你的任务	优先 Skill
查资料 / 调研 / 抓网页正文	multi-search-engine
登录态网页操作 / 抓数据 / UI 验证	browser-use
应用内可见窗口调试 / console / network	browser-use +mcp__spark_browser__*
写 React 组件 / 改样式	react（配合 frontend-design）
做有设计感的页面 / Landing	frontend-design
挑配色 / 字体 / 风格 / UX 准则	ui-ux-pro-max
生成 Spark 工作流 JSON	spark-workflow-generator
画布节点与影视流水线操作	canvas-studio
生图 / 生视频 / 配音 / 转写	multimedia-use
视频抽帧 / 转码 / 剪辑 / 字幕	video-workflow
出课件 / 专题讲解 / 数据分析报告	spark-web-tool
单张图表配置	echarts
调用 Anthropic SDK 或做模型迁移	claude-api
整理提交信息	commit
难复现 bug 的排查	spark-debug（先开会话的调试模式）
管理 Skills / MCP / Agents / Teams / 看板	platform-manager
不确定该用哪个 Skill	find-skills
写或改进一个 Skill	skill-creator

组合建议：一次会话里 2~4 个技能足够。技能越多，system prompt 里的技能目录越长， 而且在技能职责重叠时模型更容易选错（例如截图任务同时开browser-use和canvas-studio）。

9. 自己写一个 Skill

三条落地路径，按「是否要跟随项目 / 是否要分享」选：

目的	做法
只给某个项目用	在仓库里建.agents/skills/<slug>/SKILL.md（或 .claude/skills 等被扫描的目录）。跟随代码走，会话内实时可见，不进全局技能列表
给本机所有项目用	放到{userData}/skills/<slug>/，或在「技能 → 创建」里用「文件/目录导入 / 软链接 / 手动创建」，再到 Agent 页把技能分配给需要它的 Agent
发给别人	把技能推到 GitHub 仓库（目录里含SKILL.md），对方用 Agent 调 mcp__spark_platform__skills_install_github（repo/ ref/path）安装；或让维护者把它加进「精选推荐」目录

frontmatter 真实字段：name（必填，非空字符串）和 description（必填）是硬性要求；version/author/ category/tags/license可选；requiredTools与tools会被合并成依赖工具清单（写在这里只是声明， 不会自动帮你装上对应的 MCP）。category的常见取值为coding/ writing/analysis/workflow/utility； 内置技能里还出现过debugging。

---
name: sql-explain
description: "把 SQL 拆成执行步骤并解释代价。用户粘贴 EXPLAIN 输出、或问「这条 SQL 为什么慢」时加载。"
version: 1.0.0
author: Your Name
category: coding
tags: [sql, explain, performance]
requiredTools: [Bash]
---

## 何时使用
…

## 工作流
1. …

## 注意
- …

想让技能被稳定触发，关键在description：写清「做什么 + 什么场景加载 + 什么场景不要加载」。 内置技能的 description 普遍是这个写法（例如claude-api 明确列出 TRIGGER 与 SKIP）， 可以直接参考。写完用skill-creator跑一轮评测和 description 优化。

注意：内置技能的内容在安装目录里是只读的，改本机副本会在升级时被覆盖； 想长期保留自己的版本请用独立 slug 放到{userData}/skills/。

速查表

项目	内容
内置 Skill 数量	17 个（apps/desktop/resources/skills/，打包后在 process.resourcesPath/skills）
Skill id 形态	builtin:<目录名>，取自目录内 manifest.json 的 id
生效前提	分配给 Agent（skillIds）；停用走 enabled=0 / skills_toggle
不可删除	builtin: 前缀的技能只能停用
加载策略	system prompt 只放 id + 名称 + 描述；正文按需 skills_load
会话内点名	输入框「+ → 技能」插入 @技能名
项目级技能目录	.claude/skills → … → .agents/skills → skills（按顺序去重）
自定义落盘	{userData}/skills/<slug>/（scope=user）
平台工具命名空间	mcp__spark_platform__*（当前 124 个）
工作流生成校验	node scripts/validate.mjs <生成的.json>（13 种节点封闭枚举）

常见问题

内置 Skill 一共有多少个？

17 个目录（apps/desktop/resources/skills/），分别是 claude-api、commit、react、frontend-design、skill-creator、spark-workflow-generator、multi-search-engine、browser-use、canvas-studio、multimedia-use、video-workflow、spark-web-tool、echarts、ui-ux-pro-max、spark-debug、find-skills、platform-manager。每个目录是一份 SKILL.md + 一份声明 id 的 manifest.json。

一次开几个 Skill 合适？

2~4 个。技能目录（id + 名称 + 描述）会整段进 system prompt，开太多会拉长提示词，职责重叠时还容易选错技能。技能正文只有被加载时才占上下文。

为什么装了技能但对话里没生效？

技能必须分配给 Agent 才生效：到「Agent」页编辑目标 Agent，在 Skills 一栏点「管理 Skills」勾选；同时确认该技能没有被停用（enabled=0）。项目目录里的技能只在对应工作区的会话里可用。

改内置技能的文件会怎样？

内置目录随应用升级更新，改动会被覆盖；而且内置技能不能删除（删除接口拒绝 builtin: 前缀），只能停用。要长期保留自己的版本，请用独立 slug 放到 {userData}/skills/ 或项目内的被扫描目录。

spark-debug 为什么有时看不到 mcp__spark_debug__ 工具？*

它按会话挂载：只有在该会话打开「调试模式」开关后，运行时才会挂上 spark_debug MCP 并注入状态机提示词。这个开关是 per-session 的，不会从全局偏好继承。

platform-manager 到底有多少个平台工具？

以 platform-management-mcp-server.mjs 注册为准，当前 124 个（技能正文里写的 94 个是旧值）。分 17 组，最大的是 Tool Package 22 个、GitHub 15 个、Providers 13 个、自定义工具 11 个、看板任务 10 个。