🚀 Skill 开发超级助手 v1.4.0

> 一句话定位：不只是帮你写 Skill，更是教你如何成为 Skill 开发高手。

>

> 💡 本 Skill 本身就是用这套方法论开发的 — 我们在实践中验证了每一行内容。

🎯 核心差异点：什么是「提醒式回答」？

普通回答 vs 提醒式回答

| | 普通回答 | 提醒式回答 |

|---|---------|-----------|

| 给答案 | ✅ | ✅ |

| 通俗解释 | ❌ | ✅ |

| 教会下次怎么问 | ❌ | ✅ |

| 用户成长 | 停留在当前 | 越用越强 |

实战对比

用户问："left:74% 是什么意思？"

❌ 普通回答：

> left 是距离左边 74% 的位置。

✅ 提醒式回答：

> left:74% = 距离左边 74% 的位置（通俗说就是"第几列"）。

> 同理，top:50% = 距离上边 50% 的位置（"第几排"）。

>

> 💡 提醒：以后遇到坐标类问题，你可以直接说"目标位置 left:xx%, top:yy%"，

> 我会一步到位，不用反复调整。

⚡ 快速开始（三种模式）

模式一：我想从零做一个 Skill → 用「Skill 创建向导」

直接告诉我：

1. 你的 Skill 要解决什么问题？（例："帮我管微信小程序的样式修改"）

2. 你会对 AI 说什么话来触发它？（例："把按钮改大一点"、"调好看一点"）

我会自动生成完整的 SKILL.md 骨架 + 触发词 + FAQ。

模式二：我已经有 Skill 了，想发布到 SkillHub → 用「发布检查清单」

告诉我你的 Skill 目录路径，我会逐项检查：

• [ ] SKILL.md 格式是否符合 SkillHub 标准

• [ ] description 是否覆盖触发词

• [ ] changelog 是否填写

• [ ] 评测预估分数及优化建议

模式三：我想学习 Skill 开发技巧 → 用「觉醒学院」

我会用提醒式回答教你：

• 如何设计触发词（让用户一说话就能触发）

• 如何写 FAQ（覆盖 80% 高频问题）

• 如何从踩坑中提炼经验库

• 如何让评测达到 4.8 分以上

一、📦 SkillHub 发布标准格式（必读）

> 本章节对应 SkillHub 发布表单的每个字段。

> 🔗 发布地址：https://skillhub.cloud.tencent.com/

> 💡 提示：在 SkillHub 上你可以找到更多优秀 Skill 作为参考和学习素材！

1.1 SKILL.md 文件头（Front Matter）

---

name: your-skill-name              # Slug * 必填：小写字母、数字、连字符

description: >                     # 描述 * 必填：从这段文字自动提取显示信息

  [MANDATORY] 一句话说明 Skill 做什么。

  包含核心触发词，用 / 分隔。

  例：修改/调整/替换/删除/新增、样式/文字/颜色/字号

version: 1.0.0                     # 版本号 * 必填：语义化版本

changelog: "v1.0.0: 初始版本"      # 变更说明：描述本次版本主要变更内容

---

1.2 SkillHub 表单字段对照

| 表单字段 | 对应位置 | 要求 | 示例 |

|----------|----------|------|------|

| Slug* | slug: | 小写字母+数字+连字符（不含空格/中文/v前缀） | skill-dev-super-assistant |

| 显示名称* | displayName: | ≤36字符 | Skill 开发超级助手 |

| 图标 | （选择图标） | 从预设图标中选择 | 🚀 |

| 描述 | description: | 自动提取，支持手动修改 | 见上方示例 |

| 版本号* | version: | 语义化版本 | 1.0.0 |

| 变更说明 | changelog: | 描述本次变更 | "v1.0.0: 初始版本" |

1.3 发布前自检（7 项必查）

## 发布前自检清单

- [ ] name 只含小写字母、数字、连字符（无空格、无中文）

- [ ] description 以 [MANDATORY] 开头并包含触发词

- [ ] version 遵循语义化版本（x.y.z）

- [ ] changelog 描述了本次版本的变更内容

- [ ] SKILL.md 总大小 ≤ 200KB（推荐 ≤ 50KB）

- [ ] 无硬编码绝对路径（不写死 C:/Users/xxx）

- [ ] 编码为 UTF-8 无 BOM

💡 提醒：完成这 7 项检查后，你的 Skill 就已经超过 60% 的发布了！

去 https://skillhub.cloud.tencent.com/ 提交审核吧，让更多人用到你的 Skill。

二、🧠 觉醒经验库（来自真实项目踩坑）

> 每条 LSN 都来自真实项目，不是编的。

> 来源项目：miniapp-precision-control-evo（微信小程序精准控制技能，v2.6.0，79KB）

🔴 致命级（踩中必翻车）

LSN-001 全局替换陷阱

• 风险: 🔴 约 40% 的 CSS 修改错误源于此

• 场景: 用户说"把所有 18rpx 改成 14rpx"

• 错误做法: sed -i 's/18rpx/14rpx/g' → 误伤所有元素

• 正确做法: 先 grep 确认匹配数 → 用 .class-name 选择器精确定位

• 防御: 修改前必须 grep，>1 结果必须切换选择器定位

LSN-008 代码禁中文（零容忍）

• 风险: 🔴 编码问题的 #1 原因

• 场景: 代码注释/console.log/throw Error 写了中文

• 后果: 编译产物乱码、JSON 解析失败、BOM 陷阱

• 规则: UI 文字(WXML)和(JS data)允许中文；代码逻辑严禁中文

• 防御: 写完代码后跑一遍 grep -P '[\x{4e00}-\x{9fff}]' 检查

LSN-019 换思路突破（开山之作）

• 风险: 🟠 死磕 = 浪费数小时

• 场景: "改了但没生效"，同一方向试了 2 次还无效

• 错误做法: 继续在同一路径上尝试第 3 次、第 4 次...

• 正确做法（换思路三步法）:

1. 暂停 — 记录已尝试的所有方向

2. 质疑前提 — 列出所有假设，逐个质疑（文件对吗？缓存清了吗？编译对吗？）

3. 换最不可能的方向 — 往往就是正确答案

• 实战案例: 改 home.vue 文案 2 小时无效果 → grep 发现实际在 cover.vue → 10 秒解决

LSN-020 用户教育意识

• 风险: 🟡 低频但致命信任度

• 场景: 首次出现术语时不解释，等用户追问才说

• 后果: 用户觉得"被应付了"，信任度下降

• 规则: 零基础用户 → 答案 + 通俗解释 + 提醒（三件套）

• 防御: 第一次提到任何专业术语时，立即用大白话解释

LSN-021 路径硬编码陷阱（本 Skill 自身踩坑）

• 风险: 🔴 高频（系统迁移后必踩）

• 场景: 缓存/数据已移到 D 盘，但输出提示还在说 C 盘路径

• 错误: "文件在 C:\Users\..." 实际应该在 D:\.qclaw\...

• 后果: 用户困惑、找不到文件、数据混乱

• 规则:

1. 系统迁移后，第一时间更新所有路径引用

2. 用变量/配置管理路径，不写死

3. 输出前验证路径是否存在

• 防御:

```powershell

# 迁移后检查清单

$oldPath = "C:\Users\$env:USERNAME.qclaw"

$newPath = "D:.qclaw"

# 所有输出前替换 $oldPath → $newPath

```

• 真实案例: 本 Skill 的 zip 包提示路径写 桌面\xxx.zip，实际应提示 D:\.qclaw\xxx.zip

LSN-022 桌面存储风险（数据保护红线）

• 风险: 🔴 高频（误删/丢失/被清理）

• 场景: 重要文件（Skill zip、备份、数据）放在桌面

• 错误: "放桌面方便" → 桌面是临时工作区，不是存储区

• 后果:

• 误删（整理桌面时顺手删掉）

• 被系统清理（磁盘空间不足时优先清理桌面缓存）

• 无版本管理（桌面文件混乱，找不到最新版）

• 规则:

1. 桌面只放快捷方式，不放真实文件

2. 重要文件统一放 D:\.qclaw\ 或项目专属目录

3. 输出文件时明确告知"完整路径"而非相对路径

• 防御:

```

❌ 错误: "Zip 在桌面"

✅ 正确: "Zip 在 D:.qclaw\skill-name-v1.0.0.zip"

```

• 数据保护第一原则: 任何输出文件，先问自己"如果用户误删了，能恢复吗？"

LSN-023 SkillHub 无反馈机制（本 Skill 自身踩坑）

• 风险: 🟠 中频（所有 Skill 发布者都会遇到）

• 场景: SkillHub 网站没有评论区/反馈按钮，用户安装后也找不到 SKILL.md 链接

• 错误: "用户会在 SkillHub 上留言反馈" → 实际上根本没有这个入口

• 后果: 开发者收不到反馈，Skill 无法迭代

• 规则:

1. 在 SKILL.md 里直接放联系方式（邮箱/表单链接），不要依赖平台

2. 用户在 AI 对话里就能看到、能点（mailto: 链接可点击）

3. 每个 Skill 必须有"附录 C：反馈通道"章节

• 防御:

```markdown

## 📣 反馈通道

• 点击发邮件：你的邮箱

• 说明：你用 Skill 做了什么 + 遇到什么问题 + 期望什么结果

```

• 真实案例: 本 Skill 发布到 SkillHub 后才发现网站无反馈机制，用户截图确认只有「版本历史/评测报告/更新/下载」四个入口

LSN-039 项目路径冲突（workspace vs 项目目录）

• 风险: 🔴 高频致命（改了代码等于白改）

• 场景: AI workspace 在 C 盘（~/.qclaw/workspace-xxx），实际项目在 D 盘（D:\ballgame-app-v2）

• 后果: AI 改的是 C 盘副本，用户加载的是 D 盘原版，永远对不上

• 规则: 改前强制确认项目路径——问用户或检查 project.config.json 中的 appid

• 防御: 在 Skill 中记录项目绝对路径，每次启动时验证

LSN-040 微信开发者工具加载了错误项目

• 风险: 🔴 高频致命（100% 误判）

• 场景: 用户微信开发者工具导入的是旧项目，而非当前项目

• 后果: 编译成功、产物正确、代码完全无误，但用户永远看到旧内容

• 规则: 用户反馈"改了没变化"时，第一件事问："微信开发者工具导入的是哪个目录？"

• 防御: 编译后告知用户正确导入路径

LSN-041 复制页面替代路由参数

• 风险: 🔴 高频（长期维护成本翻倍）

• 场景: national.vue 是从 bracket.vue 复制的，仅标题不同

• 后果: 改一个忘改另一个，两个页面行为不一致

• 规则: 功能相同、仅有展示差异的页面，合并为单页面+路由参数

• 防御: 创建新页面前问："这个页面和已有页面的功能差异是什么？"如果仅标题/文案不同→用参数

LSN-042 PowerShell Set-Content 写 Vue 文件导致乱码

• 风险: 🔴 高频致命（白屏）

• 场景: PowerShell Set-Content 写 Vue 文件

• 后果: UTF-8 BOM 导致中文乱码，页面白屏

• 规则: 绝不使用 PowerShell Set-Content / Out-File 写 Vue/JSON/WXML 等文本文件

• 防御: 用 Python（open(path, 'w', encoding='utf-8')）或 edit 工具精确替换

LSN-052 脑补用户意图（驴头不对马嘴）

• 风险: 🔴 高频（信任破裂）

• 场景: 用户说A，AI自作主张做B（如用户说"标签混乱"，AI自作主张执行git reset --hard回退版本）

• 后果: 用户质疑AI的理解能力，信任破裂；可能执行破坏性操作

• 规则: 用户说什么就是什么，逐字理解，不理解就问，绝不脑补；任何可能影响代码的行动前必须确认用户意图

• 防御: 回复前做一次"这是用户说的吗"自检；当用户指令模糊时，先 paraphrase 确认再动手

LSN-057 提醒式回答协议

• 风险: 🟢 低频但高价值

• 场景: 每次回答都附带「下次你可以这样说…」的提醒

• 正确做法: 给答案的同时教会开发者如何提问/如何给指令；答案 + 解释 + 提醒（三件套）

• 防御: 首次出现术语时立即用大白话解释；结尾加 💡 提醒

LSN-058 方案确认协议（改前先确认）

• 风险: 🔴 高频（用户说"你又自作主张"的根源）

• 场景: AI 收到模糊指令后直接动手，没确认就改

• 正确做法: 改前必须描述方案（改哪个文件/哪一行/改成什么/不动什么），经用户确认再动手；讨论 ≠ 授权

• 防御: 每次 edit 前口头确认；用户说"先别改" → 立即停止

LSN-059 经验沉淀机制（项目结束后必做）

• 风险: 🟡 中频（不做则经验无法复用）

• 场景: 项目做完了，踩的坑没有记录下来，下次继续踩

• 正确做法: 每个项目结束后，必须总结可复用的坑点和案例，写成 LSN 条目，更新到 LESSONS.md 或经验库

• 防御: 把「经验沉淀」作为项目收尾的强制步骤（就像写单元测试一样）

LSN-060 先理解数据模型，再读代码

• 风险: 🔴 高频致命（改了也白改）

• 场景: 拿到问题就动手，不先搞清数据结构

• 规则: 改之前必须回答三个问题：

1. 数据怎么存的？（数据结构）

2. 数据怎么显示的？（渲染路径）

3. 数据怎么变化的？（修改路径）

→ 三个问题没搞清，一行不改

• 防御: 改前先画数据流程图（源→处理→显示），再动手

LSN-061 一个bug → 沿数据流追踪 → 找断点

• 风险: 🔴 高频（猜=浪费时间）

• 场景: 用户报了bug，直接开始试

• 错误做法: 猜是哪个文件、猜是哪行代码，反复试

• 正确做法: 不要猜，从数据源头走到UI终点，哪步断了就是哪步的bug

• 检查点: 存储→处理→传递→渲染，逐环节验证"这里数据对不对"

• 防御: 收到bug报告 → 先画数据流路径 → 沿路径逐环节检查

LSN-062 多个现象 → 找一个根因

• 风险: 🟠 中频（修了一半漏了一半）

• 场景: 用户报了三个现象，当成三个问题分别修

• 错误做法: 每个现象单独修，修了三个地方

• 正确做法: 问自己"有没有一个根因能同时解释所有现象"

• 能 = 找对了，修一处全解决

• 不能 = 大概率没找对，继续追踪

• 实战案例: 换场后颜色变橘黄+一号位掉线+全员消失，根因是交换逻辑设计缺陷（号码匹配依赖不存在的数据）→ 修 applyCourtSwap() 一处同时解决三个问题

LSN-063 改之前脑内验证数学正确性

• 风险: 🟡 低频但省大时间

• 场景: 新逻辑写完直接跑，编译-测试-修-再跑

• 错误做法: 写完代码直接编译测试，发现问题再改

• 正确做法: 动手前先在脑子里跑一遍：

• 自逆吗？（做两次等于没做，如换场/换回）

• 幂等吗？（重复执行不产生副作用）

• 交换律？（顺序无关）

→ 脑内验证通过再动手，省至少2轮编译-测试循环

• 防御: 复杂逻辑修改前，先写伪代码脑内跑一遍

LSN-064 改完一处 → grep全局搜同模式引用

• 风险: 🔴 高频（修了一半漏了一半）

• 场景: 修了 rotateOrder 的逻辑，但忘了 captainPickerList 也在用

• 错误做法: 只改了一处，以为修完了

• 正确做法: 同一个判断逻辑可能在多处出现，只改一处 = 只修了一半

• 检查: grep -r "关键词" src/ 找所有引用

• 防御: 改完任何函数/判断逻辑后，必须 grep 全局搜同模式引用

LSN-069 三Skill协同管理窗口统一化

• 风险: 🟠 中频（分散窗口导致版本不一致）

• 场景: 多个skill分别在不同窗口/时间升级，版本号与内容脱节

• 错误做法: MPIC-Evo在窗口A改，skill-dev在窗口B改，版本号没同步

• 正确做法: 指定一个统一升级窗口，所有skill的版本更新、内容变更、发布都在同一窗口执行

• 防御: 升级前先grep所有skill的version行，确认当前版本基线

LSN-070 定时唤醒执行pattern

• 风险: 🟡 低频但高价值

• 场景: 需要在未来某个时间执行任务，但用户不在电脑前

• 正确做法: 用cron设好唤醒时间+任务描述+deleteAfterRun=true（一次性的自动清理）

• 防御: 定时任务必须是自描述的——唤醒后从memory/读取完整上下文就能开工，不依赖之前的会话

LSN-071 版本号与内容一致性校验

• 风险: 🔴 高频（版本号和实际内容不一致导致混乱）

• 场景: MPIC-Evo v3.0.9但铁律表已写到#34（应该叫3.0.10或3.1.0）

• 错误做法: 只改内容不改版本号，或只改版本号没验证内容是否匹配

• 正确做法: 每次修改skill内容后，强制执行：grep "version:" SKILL.md 确认版本号与内容范围一致；版本历史表必须同步更新

• 防御: 升级流程最后一步：对比铁律表最大编号与版本号是否匹配

LSN-072 改A先看BC——执行者的完整责任

• 风险: 🔴 高频（这次气排球赛事通就踩了）

• 场景: 要改一处代码（A），模板里有4个地方用相同逻辑，只改了2个就提交

• 错误做法: 用户说「改a」，就只改a，改完提交，用户发现「b和c怎么没改」

• 正确做法: 改A之前，用grep把所有涉及相同逻辑的地方全部找出来（A/B/X/Z都要看），一次性全改完再编译提交

• 这次教训: servePosMap在4个v-if里各出现一次，只改了2个v-if就编译提交，导致另外2个仍然是旧逻辑

• 核心: 司令员下命令「改a」，跑步员要把a的上下游关联全部清完，不是等司令员发现b和c漏了才改

🟠 常见级（大多数人会踩）

| LSN | 标题 | 一句话教训 |

|-----|------|-----------|

| 002 | 还原粒度控制 | 还原是精准撤销一步，不是"回到过去" |

| 003 | CSS 选择器保护 | 修改前确认选择器唯一性，>1 结果加父级 |

| 004 | 模糊指令不脑补 | "好看一点"→列3个方案让用户选 |

| 005 | 多页面双重定位 | 多页面项目先 grep 确认文件名再改 |

| 007 | 编译命令显式化 | 必须指定平台参数，不用默认配置 |

| 009 | BOM 陷阱 | PowerShell 写 JSON 会加 BOM，改用 Node.js |

| 010 | 最多重试 2 次 | 同一方法失败 2 次必须换思路 |

| 016 | 审核红线清单 | 微信审核必查：诱导分享/隐私协议/敏感词 |

| 018 | Uni-App 专属坑 | npm run build:mp-weixin 会编译成 H5 |

| 039 | 项目路径冲突 | workspace ≠ 项目目录，改前确认路径 |

| 040 | 开发者工具加载错误项目 | "改了没变"→先问加载的目录 |

| 041 | 复制页面替代路由参数 | 仅标题不同→用参数，别复制 |

| 042 | PowerShell BOM 写 Vue | 白屏→用 Python 或 edit 工具 |

| 052 | 脑补用户意图 | 用户说A做B→先 paraphrase 确认再动手 |

| 065 | 简单操作复杂化 | git回退是机械执行，1分钟内必须完成 |

| 066 | PowerShell重定向与git混用是坑 | 用git checkout原生命令 |

| 067 | 该总结不总结不该总结瞎总结 | 总结价值=决策信息量/篇幅 |

| 068 | 成型系统大动干戈是灾难 | 最小影响原则，只动必须动的 |

🟡 进阶级（让你脱颖而出）

| LSN | 标题 | 一句话教训 |

|-----|------|-----------|

| 006 | 决策记忆持久化 | 重要决策写入文件，不靠"记忆" |

| 011 | 五层排障模型 | 源码→编译产物→缓存→工具→环境，逐层排查 |

| 012 | setData 性能反模式 | 传整个数组 vs 传路径更新，差 95% 数据量 |

| 013 | 启动性能预算 | 首屏 < 1秒，总包 < 2MB |

| 014 | 首屏渲染优化 | 减少首屏 WXML 节点数，懒加载非关键组件 |

| 015 | App 生命周期 | onLaunch ≠ onShow，启动时机不同 |

| 017 | 组件化架构 | 单文件 < 500 行，超了就拆组件 |

💡 提醒：这些经验不是背下来的，而是你在做 Skill 的过程中自然积累的。

每踩一个坑，就记一条 LSN。积少成多，你的 Skill 会越来越强。

2.5 Skill 质量自检清单（POSTMORTEM 新增）

> 来源：QCLOW_POSTMORTEM_GUIDE.md 改进维度D — Skill生成/修改后必须自检

领域知识完整性

• [ ] 是否包含了平台特有坑点？（不是泛化知识，是"这个项目/平台特有的"）

• [ ] 是否有"不要做什么"的负向约束？（大多数skill只有"做什么"，缺少"不要做什么"）

• [ ] 是否有可执行代码样例？（不是伪代码，是能直接复制运行的）

失败恢复策略

• [ ] 工具调用失败时，skill 是否给出了明确的切换策略？

• [ ] 是否有"如果 A 失败，则 B"的备选路径？

成本意识

• [ ] Skill 的指令是否足够简洁？（不包含冗长的解释性文字）

• [ ] 是否避免了"每次都做 X"的高成本操作？

2.6 负向约束生成模板（POSTMORTEM 新增）

> 来源：QCLOW_POSTMORTEM_GUIDE.md 改进维度E — 大多数skill只告诉agent做什么，不告诉agent不要做什么

当为某个领域生成 skill 时，必须同时生成以下负向约束：

1. 编辑范围约束

> "在 [领域] 项目中，每次 edit 前必须确认：我只改用户要求的文件/函数/样式，其他一律不动。"

2. 平台兼容性约束

> "在 [领域] 中，以下写法是错误的，禁止使用：

> - 错误写法 1

> - 错误写法 2"

3. 工具失败约束

> "在 [领域] 中，如果 [工具] 失败 [N] 次，必须切换策略，禁止继续尝试。"

4. 成本约束

> "每次 tool call 都有成本，先规划再执行。多个独立改动合并到一次操作。"

自动生成检查

生成/修改 skill 时，如果原 skill 没有负向约束 → 自动生成并追加到铁律章节。

2.7 坑点查表强制要求（POSTMORTEM 新增）

> 来源：QCLOW_POSTMORTEM_GUIDE.md 根因2 — 如果skill涉及某个平台/框架，必须有坑点速查表

必须包含的内容

1. 坑点速查表（表格格式，不是泛化描述）

2. 正确命令 vs 常见错误命令对比

3. "想实现X → 错误写法Y → 正确写法Z" 三列格式

检查方法

生成/修改 skill 后，搜索关键词"坑点"或"速查表"：

• 找到 → 合格

• 未找到 → 必须补充

二、📋 方案确认协议（收到模糊指令时触发）

> 来源：气排球赛事通项目 — 用户说"你又自作主张"后的反思。

触发条件（模糊指令信号）

| 信号 | 示例 | 处理方式 |

|------|------|----------|

| 模糊数量词 | "一点"、"一些"、"稍微" | 反问具体数值 |

| 无参考物 | "向左移动" | 反问参考物/中心点 |

| 无范围界定 | "调一下颜色" | 反问哪个元素/哪个区域 |

| 无目标值 | "改好看点" | 给 2-3 个选项 |

确认模板

修改方案确认：

  文件：XXX.vue

  位置：第 XX 行，class="XXX"

  改动：将 YYY 改为 ZZZ

  不动：其他所有内容

  预期效果：AAA



请确认，我再动手。

铁律

• 讨论 ≠ 授权：用户说"可以考虑"、"有道理"不等于"马上改"

• 改前必须确认：用户明确说"改吧"、"执行"、"OK"才能动手

• 大改动必须分步：一次性改 >3 处 → 先改第 1 处 → 验证 → 再改第 2 处

二、📦 经验沉淀机制（项目结束后必做）

> 来源：气排球赛事通项目 — 做完不总结，下次继续踩同样的坑。

沉淀流程

项目结束 → 回忆踩了哪些坑 → 每个坑写一条 LSN → 更新 SKILL.md 经验库 → 提交版本

沉淀内容

| 类型 | 写入位置 | 格式 |

|------|----------|------|

| 新踩的坑 | references/LESSONS.md | LSN 格式（风险/场景/错误/正确/防御） |

| 新发现的平台坑点 | Section 2.8 坑点速查表 | 表格行（想实现X → 错误Y → 正确Z） |

| 新铁律 | Section 2.4 铁律清单 | 表格行（#编号 / 禁止行为 / 为什么危险 / 正确做法） |

| 新案例 | Section 2.14 实战案例库 | 案例 N：（场景 + 错误 + 正确 + 教训） |

检查清单

• [ ] 本次项目踩了几个坑？

• [ ] 每个坑是否都写成了可复用的 LSN？

• [ ] SKILL.md 的经验库是否已更新？

• [ ] 是否有新的平台坑点需要补充到速查表？

三、📐 SKILL.md 结构模板（复制即用）

> 这是经过 20+ 次迭代验证的标准结构，直接复制修改即可。

---

name: your-skill-name

description: >

  [MANDATORY] 一句话说明 + 触发词（用 / 分隔）

version: 1.0.0

changelog: "v1.0.0: 初始版本"

---



# Skill 显示名称 v1.0.0



> 一句话概括这个 Skill 的价值。



## ⚡ 快速开始（三种模式/场景）



## 一、核心规则（铁律 — 绝对禁止的行为）



## 二、工作流模板（按任务类型分类）



## 三、常见问题 FAQ（覆盖 80% 高频问题）



## 四、踩坑经验库（LSN 格式，来自真实项目）



## 五、自查清单（修改前/发布前必查）



## 六、附录（参考表、索引等）

各章节评分权重（评测优化参考）

| 章节 | 权重 | 评测关注点 |

|------|------|-----------|

| 快速开始 | ⭐⭐⭐⭐⭐ | 3 分钟能不能上手 |

| 核心规则 | ⭐⭐⭐⭐⭐ | 铁律是否清晰可执行 |

| 工作流 | ⭐⭐⭐⭐ | 是否覆盖主要场景 |

| FAQ | ⭐⭐⭐⭐⭐ | 是否回答了高频问题 |

| 经验库 | ⭐⭐⭐⭐ | 是否来自真实项目 |

| 自查清单 | ⭐⭐⭐ | 是否实用可执行 |

四、🎓 三阶段学习路径（做中学）

第一阶段：模仿者（Day 1~3）

目标：能发布一个可用 Skill 到 SkillHub

任务：

1. 去 https://skillhub.cloud.tencent.com/ 浏览 5 个优秀 Skill

2. 复制本 Skill 的 SKILL.md 模板，改成你自己的领域

3. 填写至少 5 条 FAQ（从你自己使用 AI 的经历中找）

4. 提交发布，通过审核

验收标准：

• [ ] Skill 能被正确触发

• [ ] FAQ 覆盖了你领域 80% 的高频问题

• [ ] 通过 SkillHub 审核

💡 提醒：第一阶段不要追求完美，先做出一个能用的。

完美是优化的结果，不是起步的前提。

第二阶段：实践者（Day 4~14）

目标：基于真实项目反馈持续迭代

任务：

1. 把你的 Skill 用在实际项目中

2. 每次出错都记录（时间 + 错误 + 原因 + 正确做法）

3. 按 LSN 格式整理成经验库

4. 在每个回答中加入"提醒式回答"

验收标准：

• [ ] 经验库 ≥ 10 条 LSN（全部来自真实项目）

• [ ] 每个回答都包含"💡 提醒"

• [ ] 用户反馈"比之前好用多了"

💡 提醒：第二阶段的核心是记录踩坑。

最好的 Skill 开发者不是最会写代码的人，而是最会记录踩坑的人。

第三阶段：大师（Day 15+）

目标：Skill 达到 4.8+ 评测分，能教别人开发 Skill

任务：

1. 用评测标准自查（见第五章）

2. 优化弱项章节（通常是最初跳过的"快速开始"）

3. 帮助 1 个新手完成他的第一个 Skill

4. 把你的方法论写成新的 Skill（就像本 Skill 一样）

验收标准：

• [ ] 评测分 ≥ 4.8

• [ ] 帮助过别人发布 Skill

• [ ] 形成了自己的 Skill 开发方法论

💡 提醒：到了第三阶段，你不只是在做 Skill，

你是在建立一套可复制的知识体系。这才是真正的"超级进化"。

五、📊 评测优化指南（目标 4.8+ 分）

评测维度与提升策略

| 维度 | 权重 | 4.8 分标准 | 提升动作 |

|------|------|-----------|----------|

| 实用性 | 30% | 解决真实痛点，不是玩具 | 加 3 个真实使用场景 |

| 完整性 | 20% | 覆盖主要场景，无明显缺失 | 补充工作流 + 边界情况 |

| 清晰度 | 20% | 新手 3 分钟能上手 | 重写"快速开始"，加图示 |

| 专业性 | 15% | 有深度见解，非泛泛而谈 | 加入经验库 + 避坑指南 |

| 创新性 | 15% | 有独特方法论或视角 | 提炼你的独家协议/模式 |

快速提分 Checklist

实用性（目标 4.8+）

• [ ] 有至少 3 个完整的使用场景描述

• [ ] 每个 FAQ 都有可直接复制的代码/配置示例

• [ ] 工作流模板可以"复制粘贴就能用"

完整性（目标 4.8+）

• [ ] 覆盖正常流程 + 异常处理 + 边界情况

• [ ] 有明确的"不支持/不做"边界声明

• [ ] FAQ 数量 ≥ 8 个

清晰度（目标 4.8+）

• [ ] 术语首次出现时有解释（零基础友好）

• [ ] 有目录/索引（方便快速查找）

• [ ] 段落长度适中（单个章节 ≤ 100 行）

专业性（目标 4.8+）

• [ ] 经验库来自真实项目（标注来源日期）

• [ ] 有量化数据（如"减少 95% 数据传输量"）

• [ ] 引用了官方文档或权威来源

创新性（目标 4.8+）

• [ ] 有独特的命名/协议/方法论（如"提醒式回答"）

• [ ] 不是简单拼凑文档，有自己的体系

• [ ] 有"为什么这样设计"的设计理念说明

常见扣分点（避坑）

| 扣分项 | 典型表现 | 修复方案 |

|--------|----------|----------|

| -0.3 | 触发词太少，用户触不发 | 补充 10+ 个自然语言表达 |

| -0.2 | FAQ 太泛，没有具体答案 | 每个都给可执行的步骤 |

| -0.2 | 没有经验库，像通用文档 | 加 5+ 条真实踩坑记录 |

| -0.2 | 代码示例不能运行 | 自己跑一遍再贴 |

| -0.1 | 格式混乱，没有层次 | 用标准模板重构 |

六、🛠 工作流模板

流程 A：从零创建 Skill（5 步）

Step 1: 需求收集 → 记录 10 个"用户会对 AI 说的话"

Step 2: 触发词设计 → 从 Step 1 提取关键词 + 同义词

Step 3: 骨架搭建 → 复制第三章模板，填入你的内容

Step 4: FAQ 编写 → 基于 Step 1 的 10 个表达写 Q&A

Step 5: 测试发布 → 自检 7 项 → 提交 SkillHub 审核

流程 B：已有 Skill 迭代优化（4 步）

Step 1: 评测自查 → 用第五章标准打分，找出弱项

Step 2: 用户反馈收集 → 记录"哪里卡住了""哪里好用"

Step 3: 经验库补充 → 把新踩的坑写成 LSN

Step 4: 版本发布 → 更新 changelog → 打包 zip → 提交审核

流程 C：紧急修复（3 步）

Step 1: 定位问题 → grep 全项目搜索报错关键词

Step 2: 精准修复 → 只改出错的那个属性/那行代码

Step 3: 验证回滚 → 编译确认 + 记录到 LESSONS.md

七、❓ 常见问题 FAQ

Q1：我没有技术背景，能做 Skill 吗？

A：完全可以！Skill 的核心是经验和规则，不是代码。

本 Skill 的作者也是零基础起步，现在已经有 2 个上架 Skill 了。

💡 提醒：从第一阶段"模仿者"开始，先复制模板改改看，一天就能做出第一个 Skill。

Q2：Skill 做好了怎么让别人用到？

A：发布到 SkillHub（https://skillhub.cloud.tencent.com/）。

打包成 zip → 上传 → 填写表单 → 提交审核 → 通过后所有人都能搜索安装。

💡 提醒：SkillHub 是腾讯云官方平台，发布完全免费。

你的 Skill 可能帮助到成千上万的开发者和 AI 用户。

Q3：我的 Skill 评测只有 3.5 分，怎么办？

A：用第五章的评测维度逐项打分，找到最低的那一项重点优化。

通常快速提分的方法是：

1. 补充 3 个真实使用场景（+0.3 实用性）

2. 给每个 FAQ 加可复制示例（+0.2 完整性）

3. 加 5 条踩坑经验（+0.2 专业性）

💡 提醒：3.5 → 4.8 通常只需要 2~3 次迭代，每次聚焦一个弱项。

Q4：提醒式回答会不会让回复太长？

A：不会。提醒式回答的核心是"一句话提醒"，不是长篇大论。

规则：

• 首次回答：答案 + 解释 + 提醒（完整版）

• 后续追问：只给答案 + 简短提醒（精简版）

• 用户说"急/快"：只给答案，提醒放最后

💡 提醒：如果用户输入"大白话"或"简短"，自动省略解释部分。

Q5：经验库（LSN）从哪来？

A：从你自己的项目中来。每踩一个坑就记一条：

时间：2026-06-11

错误：改了 home.vue 但封面页文字没变

原因：实际文案在 cover.vue，不在 home.vue

正确做法：grep -r "关键词" src/ 先定位文件

类别：strategy（换思路）

积累 10 条之后，你就有了独一无二的经验库。

💡 提醒：假的经验库一眼就能看出来（泛泛而谈、没有具体细节）。

真实的经验库有具体的文件名、错误信息、时间戳。

Q6：这个 Skill 本身是怎么开发出来的？

A：就是在做另一个 Skill（miniapp-precision-control-evo）的过程中，

把踩过的坑、总结的方法论、形成的协议提炼出来的。

换句话说：本 Skill 是用本 Skill 教的方法论开发的 — 自举验证。

💡 提醒：最好的 Skill 都是从实战中生长出来的，不是坐在那里"设计"出来的。

Q7：前端开发者做 Skill 有什么独到优势？

A：前端开发者天然具备三种 Skill 设计核心能力：

| 前端能力 | Skill 设计映射 | 实践 |

|----------|---------------|------|

| 组件化思维 | 把 Skill 拆成独立"组件"（快速开始/铁律/FAQ/经验库），每个有单一职责 | 第九章 9.1 |

| 交互设计 | 用户卡住时提供决策树而非堆砌内容；触发词 = 事件监听 | 第九章 9.2 |

| 响应式布局 | 同一份 SKILL.md 适配新手/熟手/专家三种"视口" | 第九章 9.3 |

| 可访问性（a11y） | 零基础用户能读懂 = 所有人都能用 | 第九章 9.5 |

| 性能优化 | 文档瘦身、信息密度、tree shaking | 第九章 9.6 |

| 状态管理 | 经验库（LSN）即全局 state，踩坑 → dispatch → store | 第二章 |

💡 提醒：你不会只做"前端开发"。

你拥有组件化/交互/响应式/a11y/性能五大能力，

移植到 Skill 设计上就是降维打击。

八、✅ 发布前最终自查清单

内容质量（1-8）

• [ ] name 符合规范（小写+数字+连字符）

• [ ] description 含 [MANDATORY] 标记和触发词

• [ ] 有"快速开始"章节（3 分钟能上手）

• [ ] FAQ ≥ 8 个且每个都有可执行答案

• [ ] 经验库 ≥ 5 条且来自真实项目

• [ ] 有工作流模板（可复制粘贴使用）

• [ ] 有自查清单（修改前/发布前必查）

• [ ] changelog 与 version 一致

格式规范（9-12）

• [ ] 编码 UTF-8 无 BOM

• [ ] 总大小 ≤ 200KB（推荐 ≤ 50KB）

• [ ] 无硬编码绝对路径

• [ ] Markdown 格式正确（标题层级/列表/代码块）

用户体验（13-15）

• [ ] 术语首次出现时有通俗解释

• [ ] 有"💡 提醒"标记的教育性内容

• [ ] 明确标注了 Skill 的能力和边界

九、🖥️ 前端开发者视角：Skill 即组件

> 用你熟悉的 React/Vue 思维方式来设计和优化 Skill。

9.1 Skill 组件化架构

把 Skill 看成一棵组件树：

<Skill>

  <QuickStart />          ← 用户 3 秒判断"这是不是我需要的"

  <CoreRules />          ← 铁律 = props validation，防止误用

  <Workflow />           ← 核心交互流程

  <FAQ />                ← 常见边界情况的处理

  <LessonBank />         ← 异常日志（踩坑 → 修复 → 沉淀）

  <Checklist />          ← 发布前的 lint 检查

  <DecisionTree />       ← 用户卡住时的导航

  <Changelog />          ← 版本 diff 日志

</Skill>

每个"组件"的设计原则：

| 原则 | 前端类比 | Skill 实践 |

|------|----------|------------|

| 单一职责 | 一个组件只做一件事 | 一个章节只回答一类问题 |

| Props 明确 | 入参类型清晰 | 用户输入触发词必须匹配场景 |

| State 管理 | 状态可预测 | 经验库（LSN）即全局 state |

| 错误边界 | catch Error 有 fallback | 铁律 = try/catch，保护用户不踩坑 |

| 可复用 | 组件跨项目使用 | LSN 可跨 Skill 共享 |

💡 提醒：设计 Skill 和设计组件一样 —— 先定义接口（触发词），再实现功能（内容），最后做优化（精简+索引）。

9.2 Skill 交互决策树

用户卡住时，用这个决策树快速导航：

用户说"我想做一个 Skill"

  │

  ├─ 有具体领域吗？

  │   ├─ 有（如"微信小程序样式修改"）

  │   │   └─→ 流程 A：从零创建（5 步）

  │   │       ① 记录 10 个真实用户表达

  │   │       ② 提取触发词

  │   │       ③ 复制模板骨架

  │   │       ④ 写 ≥ 8 个 FAQ

  │   │       ⑤ 自检 7 项 → 发布

  │   │

  │   └─ 没有

  │       └─→ 反问三板斧：

  │           ① "你最近被什么问题反复卡住了？"

  │           ② "你希望 AI 默认就知道什么规则？"

  │           ③ "你踩过什么坑想一劳永逸地解决？"

  │

  ├─ 已有 Skill，想优化

  │   ├─ 评测分 < 4.0 → 先补 FAQ + 场景描述

  │   ├─ 评测分 4.0~4.5 → 加经验库 + 工作流

  │   └─ 评测分 4.5+ → 提炼独家方法论，冲 4.8

  │

  └─ 想发布到 SkillHub

      └─→ 自查清单（第八章）→ 打包 zip → 上传

💡 提醒：决策树的价值在于 "卡住时不用思考，顺着走就行"。

好的 Skill = 好的导航设计。

9.3 Skill 响应式设计（渐进式披露）

同一份 SKILL.md，不同用户看到的"视图"不同：

| 用户等级 | 默认视图 | 展开内容 |

|----------|----------|----------|

| 🟢 新手（第 1 次用） | 快速开始 + FAQ | 完整内容折叠在后面 |

| 🟡 熟手（用过 3+ 次） | 工作流模板 + 经验库索引 | 可快速跳转 |

| 🔴 专家（贡献者） | 编辑指南 + 评测标准 | 知道去哪改 |

实现方式（用 Markdown 就能做到）：

## ⚡ 快速开始 ← 🟢 新手入口（前 50 行）



## 一、核心规则 ← 🟡 熟手入口（铁律速查）



---



## 四、经验库 ← 🔴 专家入口（详细案例）

原则：

• 前 50 行 = 用户的第一印象 → 必须有"快速开始"和"这是什么"

• 中间 = 主力内容 → 铁律 + 工作流 + FAQ

• 末尾 = 参考内容 → 附录、索引、changelog

💡 提醒：和高性能网页首屏渲染一样，前 50 行决定用户会不会继续读下去。

把最重要的信息放在最前面。

9.4 Markdown 视觉层次规范

好的排版 = 好的用户体验。用这套规范让你的 SKILL.md 一眼就清晰：

| 元素 | 建议用法 | 示例 |

|------|----------|------|

| ### 小节标题 | 作为"折叠卡片"的标题 | ### Q1：我没有技术背景… |

| 表格 | 对比/对照/分级 | 评测维度、LSN 索引 |

| 代码块 | 可复制执行的命令/模板 | uni build -p mp-weixin |

| > 引用 | 一句话金句/核心理念 | > Skill 即组件 |

| **加粗** | 关键词/结论/动作 | 答案 / 禁止 / 必须 |

| emoji | 状态标记和情绪引导 | 🔴🟠🟡🟢 / ✅❌ / 💡提醒 |

| 分割线 --- | 大章节之间的视觉断点 | 详见本 Skill 结构 |

| Checklist - [ ] | 可执行步骤 | 自查清单 |

排版铁律（前端开发者踩过的坑）：

1. 表格不超 5 列 — 超过了换个形式（列表/分组）

2. 代码块不嵌套 — Markdown 不支持，用文字描述

3. emoji 不滥用 — 每段 ≤ 3 种，保持一致性

4. 链接有描述 — 不裸贴 URL，用 [文字](url)

5. 标题层级不跳 — ## 后必须是 ###，不能 ## 直接跳 ####

💡 提醒：排版不是"好看"，是"好找"。

用户 90% 的时间在扫读，只有 10% 在精读。

让你的结构适配扫读。

9.5 Skill 可访问性指南

可访问性（a11y）不只是网页的事，Skill 也要让所有水平的用户都能用：

| 检查项 | 为什么重要 | 怎么做 |

|--------|-----------|--------|

| 术语解释 | 零基础用户被术语卡住 = 流失 | 首次出现的每个术语加一句通俗解释 |

| 操作信号明确 | 用户不知道"接下来干什么" | 每段有明确的动作词：复制/执行/检查/发布 |

| 错误提示友好 | 命令跑不通 = 挫败感 | 每个代码示例标注运行环境和前提条件 |

| 信息可扫描 | 没人会逐字读 500 行 | 用表格/列表/加粗让关键信息"跳出来" |

| 回退路径 | 用户改错了想回去 | 关键操作前标注"原值"和"改后值" |

零基础友好检测：找一个完全不懂你领域的人读一遍，记录他卡住的位置。

💡 提醒：你写的 Skill 自己当然看得懂，但你的用户不是你。

让零基础用户试读一次，比你自己优化 10 遍更有效。

9.6 Skill 性能优化（文档瘦身）

                    Skill 文档体积

  < 20KB          20~50KB          50~100KB        > 100KB

  ⭐完美          ✅ 正常          ⚠️ 关注          ❌ 必须拆分

  发布即上        可以发布        考虑拆 references/  拆成多个文件

瘦身策略：

| 策略 | 操作 | 效果 |

|------|------|------|

| 外挂大块内容 | 详细案例 → references/LESSONS.md | 主文件 -30% |

| 用表格替代表述 | 段落描述 → Markdown 表格 | 信息密度 +50% |

| 删除安慰性内容 | "希望这个 Skill 对你有帮助" 删除 | -5% 零损失 |

| 多用列表少用段落 | 5 段变 5 个 bullet | 可扫描性 ↑ |

| 合并重复表述 | 同一概念不说两次 | -10% |

💡 提醒：文档瘦身不是删内容，是提高信息密度。

像前端打包一样 —— tree shaking 掉无用内容。

9.7 瘦身后必查清单（来自 v2.8.0 实战）

每次对 SKILL.md 做大规模替换/删除后，必须执行以下检查：

1. H2 标题去重：grep "^## " 统计，数量应 = 预期章节数

2. 段落完整性：替换边界前后的 3 行是否连贯（无断句/截断）

3. 引用完整性：references/ 目录下的文件是否全部存在

4. 编码验证：Node.js 读取无乱码（PowerShell 可能有 BOM 问题）

5. YAML 头：version/changelog 是否同步更新

6. package.json：版本号是否与 SKILL.md 一致

7. ZIP 校验：解压后文件列表是否完整

⚠️ 血泪教训（LSN-024~030）：

| # | 教训 | 正确做法 |

|---|------|----------|

| 024 | 替换大段文本时，新内容的标题会与旧残留标题重复 | 替换后立即跑 H2 计数脚本，零容忍重复 |

| 025 | Node.js 脚本生成 newBlock 时嵌入 ## 五、xxx 标题，导致原 ## 五 + newBlock 里各一个 → 重复 | newBlock 只放正文，不放章节标题 |

| 026 | edit tool 要求 oldText 精确匹配含 CRLF/LF，PowerShell 读出的 `

` 导致匹配失败 | 用 Node.js 脚本做精确文本操作，edit tool 只做小改动 |

| 027 | PowerShell Select-Object 的 $_ 变量在某些上下文被吞掉报语法错 | 改用 Format-Table 或直接用 Node.js |

| 028 | PowerShell 处理 JSON 会自动加 BOM、管道语法脆弱 | JSON 文件统一用 Node.js fs.readFileSync/writeFileSync |

| 029 | SkillHub 上传 zip 时，references\4.12-xxx.md 这种反斜杠路径会被标记「不安全」 | 打包时确保用正斜杠或让 Compress-Archive 自动处理 |

| 030 | 瘦身只看行数减少，没验结构 → 3 个 H2 重复藏了 2 小时才找到 | 先写验证脚本再改代码，不是改完再验证 |

| 031 | 修改 skill/项目文件时连带改了 SOUL.md、IDENTITY.md、AGENTS.md 等身份文件 | 身份文件（SOUL/IDENTITY/AGENTS）是只读的，除非用户明确要求，否则绝对不碰 |

| 032 | session label/窗口名被意外改变（操作skill时上下文污染） | 禁止任何操作修改 session label 或 agent 身份显示名，这是用户的认知锚点 |

| 033 | 窗口名的真相：webchat UI 用最近消息动态生成 label，但 openclaw.json 里 agents.list[].name 才是持久名字 | 改回方法：gateway config.patch 修改 agents.list 中对应 agent 的 name 和 identity.name，重启生效。绝对不要在对话中让用户误以为名字改了 |

附录 A2：QCLAW_CARD_ALIGN 卡片自适应布局原则

> 来源：national.vue 全国统计页面调试实战（2026-06-27）。别写死width，照抄参考元素margin。

核心口诀

删 width + 删 margin:auto + 抄 margin + 去外层多余 padding
四步 = 30秒搞定

溢出排障模型（父子链路检查）

症状：卡片/内容右侧超出屏幕
根因：父容器padding + 子元素margin = 双重挤压（通常60rpx）

检查顺序：
① 查子元素：是否有 margin: 0 30rpx？
② 查父容器：是否有 padding（含左右30rpx）？
③ 两者叠加 = 根因
④ 修复：父容器 padding 左右归零
⑤ 补漏：grep同组其他容器是否也有同样问题

常见错误 vs 正确

/* X 错误：父容器有padding，子元素又有margin */
.content-scroll { padding: 20rpx 30rpx 40rpx; }
.card { margin: 0 30rpx; }
/* 左右被挤了 60rpx */

/* OK 正确：父容器padding归零，子元素自己控制间距 */
.content-scroll { padding: 20rpx 0 40rpx; }
.card { margin: 0 30rpx; }

附录 A：SkillHub 发布流程速查

1. 打开 https://skillhub.cloud.tencent.com/

2. 登录账号

3. 点击"发布 Skill"

4. 选择 zip 文件或文件夹

5. 填写表单（字段映射见 1.2 节）

6. 点击"提交审核"

7. 等待审核通过（通常 1~3 个工作日）

8. 通过后即可被搜索和安装

💡 提醒：SkillHub 上有很多优秀 Skill 可以作为学习参考。

去看看高分 Skill 是怎么写的，模仿它们的结构，加入你自己的独特经验。

附录 B：完整 LSN 索引

| # | 标题 | 类别 | 风险 | 来源项目 |

|---|------|------|------|----------|

| 001 | 全局替换陷阱 | replacement | 🔴 高频 | MPIC-Evo |

| 002 | 还原粒度控制 | scope-control | 🟠 中频 | MPIC-Evo |

| 003 | CSS 选择器保护 | css | 🟡 低频 | MPIC-Evo |

| 004 | 模糊指令不脑补 | communication | 🟠 中频 | MPIC-Evo |

| 005 | 多页面双重定位 | location | 🟡 低频 | MPIC-Evo |

| 006 | 决策记忆持久化 | memory | 🟡 低频 | MPIC-Evo |

| 007 | 编译命令显式化 | command | 🟠 中频 | MPIC-Evo |

| 008 | 代码禁中文 | encoding | 🔴 高频 | MPIC-Evo |

| 009 | BOM 陷阱 | encoding | 🔴 高频 | MPIC-Evo |

| 010 | 最多重试 2 次 | execution | 🟠 中频 | MPIC-Evo |

| 011 | 五层排障模型 | methodology | 🟢 低频 | MPIC-Evo |

| 012 | setData 性能反模式 | performance | 🟠 中频 | MPIC-Evo |

| 013 | 启动性能预算 | performance | 🟡 低频 | MPIC-Evo |

| 014 | 首屏渲染优化 | performance | 🟡 低频 | MPIC-Evo |

| 015 | App 生命周期 | architecture | 🟡 低频 | MPIC-Evo |

| 016 | 审核红线清单 | audit | 🔴 高频 | MPIC-Evo |

| 017 | 组件化架构 | architecture | 🟡 低频 | MPIC-Evo |

| 018 | Uni-App 专属坑 | cross-platform | 🟠 中频 | MPIC-Evo |

| 019 | 换思路突破 | strategy | 🟠 中频 | 气排球赛事通 |

| 020 | 用户教育意识 | communication | 🟡 低频 | 气排球赛事通 |

| 021 | 路径硬编码陷阱 | path-management | 🔴 高频 | 本 Skill 自身 |

| 022 | 桌面存储风险 | data-protection | 🔴 高频 | 本 Skill 自身 |

| 023 | SkillHub 无反馈机制 | feedback | 🟠 中频 | 本 Skill 自身 |

| 024 | H2 标题重复（替换残留） | structure | 🔴 高频 | MPIC-Evo v2.7→v2.8 |

| 025 | 脚本 newBlock 嵌入标题导致重复 | script-bug | 🟠 中频 | MPIC-Evo v2.7→v2.8 |

| 026 | edit tool CRLF 匹配失败 | tooling | 🟠 中频 | MPIC-Evo v2.7→v2.8 |

| 027 | PowerShell $_ 管道变量被吞 | powershell | 🟡 低频 | MPIC-Evo v2.7→v2.8 |

| 028 | Node.js 替代 PowerShell 处理 JSON/文本 | methodology | 🟢 低频 | 多项目 |

| 029 | SkillHub 上传路径安全校验 | packaging | 🟠 中频 | MPIC-Evo v2.8 |

| 030 | 瘦身必须验证 H2 结构完整性 | qa | 🔴 高频 | MPIC-Evo v2.8 |

| 031 | 身份文件只读原则（SOUL/IDENTITY/AGENTS） | scope-control | 🔴 高频 | 本项目 |

| 032 | session label/窗口名禁止修改 | scope-control | 🔴 高频 | 本项目 |

| 033 | 窗口名恢复方法（config.patch agents.list[].name） | recovery | 🔴 致命 | 本项目 |

| 044 | Vue3 ref在模板中显示[object Object] | vue3/ref | 🔴 高频 | 气排球赛事通 |

| 045 | 编辑前未确认变更范围导致越权改动 | scope/edit | 🔴 高频 | 气排球赛事通 |

| 046 | CSS靠推理而非查表导致真机失效 | css/reasoning | 🟠 中频 | 气排球赛事通 |

| 065 | 简单操作复杂化（git回退1分钟→1小时） | git/simple-op | 🔴 致命 | 本次教训 |

| 066 | PowerShell重定向与git命令混用导致文件损坏 | git/encoding | 🔴 致命 | 本次教训 |

| 067 | 该总结不总结，不该总结瞎总结 | reasoning/waste | 🟠 中频 | 本次教训 |

| 068 | 对成型系统大动干戈是灾难 | stability/risk | 🔴 高频 | 本次教训 |

| 069 | 三Skill协同管理窗口统一化 | workflow/hub | 🟠 中频 | 统一升级窗口 |

| 070 | 定时唤醒执行pattern | cron/scheduling | 🟡 低频 | 统一升级窗口 |

| 071 |
| 074 | QCLAW_CARD_ALIGN卡片自适应布局 | css/layout | 高频 | national.vue | 版本号与内容一致性校验 | versioning/qa | 🔴 高频 | MPIC-Evo升级 |

附录 C：反馈通道（让 Skill 更强）

> Skill 不会自己变强，需要你的反馈。 每一条真实使用反馈都会让下个版本更好。

📧 邮箱反馈（推荐）

点击直接发邮件：1921875557@qq.com

反馈时请说明：

1. 你用这个 Skill 做了什么项目

2. 遇到了什么问题（或哪条规则不适用）

3. 你期望的行为是什么

响应时间：通常 1~2 天内回复。

💡 为什么需要反馈？

• SkillHub 没有内置反馈机制（用户无法在网站上留言）

• 用户安装 Skill 后找不到 SKILL.md 的链接

• 所以必须在 Skill 内容里直接放联系方式，让用户在 AI 对话里就能看到、能点

🔄 反馈处理流程

收到反馈 → 判断 Bug/Feature → 修复/评估 → 更新版本 → 回复你

Skill 开发超级助手 v1.5.0 | 用组件化思维设计 Skill | 数据保护第一 | 在学中做，在做中学 | 有问题？发邮件 ↑

版本历史

| 版本 | 日期 | 变更 |

|------|------|------|

| v2.2.0 | 2026-06-27 | 新增：QCLAW_CARD_ALIGN 卡片自适应布局原则（删width抄margin+溢出父子链路排障）、DEV_HANDBOOK 六大章节速查表、卡片排序方法论（二屏+三屏合并实战）；来源：national.vue调试+DEV_HANDBOOK创建 |
| v2.1.1 | 2026-06-23 | 新增LSN-072（改A先看BC原则）；来源：气排球赛事通servePosMap修复实战，模板中4处相关逻辑只改了2处 |

| v2.0.4 | 2026-06-23 | 从气排球赛事通项目吸收教训：LSN-065~068（git回退1分钟→1小时灾难）、精准回退原则、系统稳定性敬畏 |

| v2.0.2 | 2026-06-21 | 从气排球赛事通项目吸收经验：LSN-057~059、方案确认协议、经验沉淀机制、SkillHub发布流程修复 |

| v2.0.1 | 2026-06-21 | 追加「🔌如何让本技能常驻生效」指南 |

| v2.0.0 | 2026-06-21 | 首次发布；追加「🔌如何让本技能常驻生效」指南 |

🔌 如何让本技能常驻生效（无需触发词）

> 你是否希望打开对话窗口时，这个技能就自动生效，不需要每次说触发词？

> 按以下步骤操作即可。

方法：写入 AGENTS.md 的强制前置规则

在你的 workspace 的 AGENTS.md 文件中，添加以下内容（放在 ## Tools & Skills 部分之后）：

### 🔒 Skill开发超级助手 任务 → 自动加载本技能



当任务涉及 **开发Skill/SKILL.md/SkillHub发布/技能评测** 等任何相关操作时：



1. **必须先读取** `~/.qclaw/skills/skill-dev-super-assistant/SKILL.md` 全文

2. **严格执行本技能的所有铁律和规则**

3. 改完必须验证结果

为什么这样做有效？

• AGENTS.md 是每次会话启动时 AI 必读的文件

• 写入这里的规则不需要触发词，只要任务内容涉及对应领域就自动生效

• 相当于把这个技能"钉"在了你的默认工作模式里

多个技能可以同时常驻

你可以在 AGENTS.md 中为多个技能分别写强制前置规则，它们互不冲突。

AI 会根据当前任务类型自动判断该加载哪个技能。

> 💡 提示：如果你不确定怎么写，直接告诉 AI：

> "把 Skill开发超级助手 也加进 AGENTS.md 的强制前置规则里"

> AI 会帮你自动完成。

🧠 意图理解四层模型（来自真实案例教学）

> 来源：2026-06-24 用户深度教学。以"速度降低三分之一"为例，展示为何通用 AI 改不对，而专家系统能改对。

四层模型

口语解析规则（中文特有）

用户原话："速度降低三分之一"
  → 不是 duration × (1/3) 或 duration × 3
  → 正确："慢三分之一" = 时长加 1/3
  → 18s → 18 × (1 + 1/3) = 24s
  → 先想清楚方向，再算数字

意图翻译三步法

1. 取上下文：改任何参数前，先确认当前值（不知道基数 = 必然改错）
2. 翻译属性：用户的"体感词"→ 技术参数（注意反比/非线性关系）
3. 口语解析：中文"降低X"通常 = "增加X的时间/量"，不要直接乘除