# Skill开发指南 ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- > 💡 开源地址：[https://github.com/Quectel-Pi/QPi-Skills]() 本文介绍开源 **Skill**：遵循 Agent Skills 格式、可直接使用的 Agent Skill，覆盖代码与仓库、部署与设备、文档与交付、环境与终端等。这里的 Skill 主要基于 Quectel Pi 智能主控板，欢迎大家一起贡献、丰富。 阅读指引：想了解概念 →「Skill 是什么」；想直接用 →「技能索引」与「技能详解」；想自己写 →「如何编写一个 Skill」。 前置条件：已在设备上完成 Hermes Agent 的部署与配置。 ## Skill 是什么 Skill 是 Agent 的能力单元，用一份 Markdown 说明「什么时候用、怎么做、做完输出什么」。它把一次成功的操作固化成可复用的流程，而不是每次重新描述一遍。 | **特点** | **说明** | | --- | --- | | 零代码扩展 | 一份 `.md` 文件 = 一项能力，不需要改代码或重新编译 | | 自然语言触发 | 用一句话描述意图即可，不需要记命令和参数 | | 即插即用 | 文件放入 Agent 的 skills 目录，重新加载后生效 | | 可持续演进 | 遇到新问题就把做法写回 Skill，下次自动生效 | ## 快速开始 在 Hermes 中，一个 Skill 就是一个目录：目录里放一份 `SKILL.md`，说明「什么时候用、怎么做、做完输出什么」，可选再带 `references/`、`scripts/` 等辅助文件。Skill 统一存放在 `~/.hermes/skills/` 下： ``` ~/.hermes/skills/ ├─ doc-consistency-audit/ # 文档一致性审计 │ └─ SKILL.md ├─ project-reproduction/ # 项目复现与部署排障 │ └─ SKILL.md ├─ github-repo-review-and-design/ # 整仓审查与仓库设计 │ └─ SKILL.md ├─ ... # 其余技能见「技能索引」 └─ / # 新增一项能力：加一个目录即可 └─ SKILL.md ``` **生效机制**：每次新会话启动时，Hermes 会扫描 `~/.hermes/skills/`，把每个 Skill 的 `name` 与 `description` 注入系统提示；当你的任务匹配某个 Skill 的触发条件（写在 description 里），Hermes 自动加载该 Skill 的完整内容，按其中定义的流程执行——不需要手动指定。 使用步骤： 1. 将 Skill 目录放入 `~/.hermes/skills/`（或用 `hermes skills install` 一键安装）； 2. 在对话中输入 `/reload-skills`，或直接开启新会话，让 Hermes 感知新 Skill； 3. 运行 `hermes skills list`，确认 Skill 已在列表中； 4. 用自然语言描述意图，Hermes 自动匹配对应 Skill 并执行。 > **说明**：除手动放置外，Hermes 还支持从 Skill Hub、URL 或 GitHub 仓库安装 Skill（`hermes skills install `）；也可以在启动时用 `hermes -s ` 预加载，或在对话中用 `/skill ` 手动加载。 ## 技能索引 本表是仓库当前 **全部技能**，技能名可点击跳转仓库目录。表中技能均为「稳定」状态，若出现试验或废弃技能会在版本号后标注。 > 分类含义：**代码与仓库**＝写代码、审仓库、发布前把关；**部署与设备**＝装环境、连板子、跑脚本；**文档与交付**＝写文档、审文档、交付留痕；**环境与终端**＝本机 shell 与平台差异。 | **技能** | **版本** | **分类** | **一句话说明** | **典型触发语** | | --- | --- | --- | --- | --- | | [code-authoring]() | 0.1.0 | 代码与仓库 | 注释只写 why + 最小充分改动，让 diff 可评审 | 写新功能、改他人代码之前 | | [github-repo-review-and-design]() | 0.1.0 | 代码与仓库 | 整仓分级审查（评估档 / 发布档）+ 新项目目录结构设计 | 看下这个仓库值不值得用 | | [prepublish-repo-audit]() | 0.1.0 | 代码与仓库 | 开源或交付前的门禁：可见性、密钥、内部标识、仓库卫生 | 这个仓能公开吗 | | [project-reproduction]() | 0.1.0 | 部署与设备 | 按教程复现 / 部署，报错按最优路径修复并固化进文件 | 按这份教程复现、部署、跑通 | | [shell-script-hardening]() | 0.1.0 | 部署与设备 | 安装与部署脚本幂等、失败可诊断、成功不自欺 | 写或改一键安装脚本 | | [adb-device-toolkit]() | 0.1.0 | 部署与设备 | adb 认设备、认清执行身份、传文件双边校验、长任务脱离会话 | 连开发板 / Android 设备调试 | | [windows-shell-tooling]() | 0.1.0 | 环境与终端 | Windows + git-bash 的路径 / 换行 / 编码 / 落盘坑 | 命令在 git-bash 里行为不对 | | [feishu-docs-api]() | 0.1.0 | 文档与交付 | REST 直写 / 同步 / 归档飞书云文档（docx / wiki / 多维表格） | 改这篇飞书文档、把 md 同步上云 | | [doc-consistency-audit]() | 0.1.0 | 文档与交付 | 批量文档 / 多语言镜像的一致性检查 + 分级报告 | 这批文档审一遍 | | [deliverable-pack]() | 0.1.0 | 文档与交付 | 把一次性工作沉淀成可复核的五件套 | 复现、迁移、调研做完要交接 | ### 获取方式 - 仓库地址： https://github.com/Quectel-Pi/QPi-Skills - 克隆后把需要的技能复制进 Agent 技能目录：`git clone https://github.com/Quectel-Pi/QPi-Skills.git`，再 `cp -r QPi-Skills/skills/* ~/.hermes/skills/` - Hermes 用户也可直接订阅：`hermes skills tap add Quectel-Pi/QPi-Skills` - 其他支持 Agent Skills 格式的客户端：`npx skills add Quectel-Pi/QPi-Skills` > 提示：每项技能都是一份自包含的 SKILL.md，按需取用；技能会随工作流持续演进，版本号以仓库 README 为准。 ## 技能详解 下面三节是仓库中最具代表性的三个技能：doc-consistency-audit（文档一致性审计）、project-reproduction（项目复现）、github-repo-review-and-design（整仓审查与仓库设计）。每个技能只摘录定义要点——完整定义以仓库中的 SKILL.md 为准。 ### 详解 1：文档一致性审计 #### 你将完成 把一批文档（一个目录树、一个知识库、一个产品线）或中英镜像文档树交给 Agent，得到一份可复现的一致性审计报告：机械层扫描链接 / 代码块 / 占位残留 / 术语 / 版式，语义层抽查漏章与数字不符，问题按严重级带定位信息输出；确定性问题边审边改、直接回写。 #### 适用场景 - 一批文档（一个目录树、一个知识库、一个产品线）交付前检查； - 中英（或多语言）镜像文档树：确认两侧是否同步、是否漏译； - 版本发布前的文档回归：占位行、TODO、失效链接、命令块错误。 #### 前置条件 - 明确检查范围与镜像关系（哪些文档是同一内容的不同语言版本）； - 拿得到文档源：本地 md、仓库或平台 API 均可（机械层只依赖纯文本）。 #### Skill 定义 规则与流程一体：Skill 定义「怎么查、怎么交付」，检查口径由内置清单决定——机械层全量扫描（脚本能查的绝不靠肉眼），语义层抽查；每条发现都带文件、位置、证据片段与严重级，第三方可复现定位。 ```markdown --- name: doc-consistency-audit description: Use when 一批文档 / 多语言镜像文档交付前做一致性审计。 --- ## 流程（Procedure） ① 定范围与镜像对：列待查清单，建「中文 ↔ 英文」配对表（按路径 / 内容指纹配对，不靠标题字面） ② 机械层扫描（可脚本化优先）：链接、代码块、占位残留、术语变体、版式——命中即给「文件 + 行号 + 片段」 ③ 语义层抽查：结构与宣称是否一致、数字与配置一致、镜像一致性、图文对应 ④ 结果落成 findings：每条一条「文件 | 位置 | 问题类型 | 证据片段 | 严重级 | 建议」 ⑤ 出报告：一句话结论 → 按严重级分组 → 每类问题给「可 Ctrl+F 定位的短片段 + 数量」 ## 修复纪律（Fix Discipline） - 确定性问题直接修（错别字、链接编码、占位行、命令粘连），边审边改不必逐条请示 - 镜像同步：改了中文版，必须同步检查 / 修改对应英文版（反之亦然） - 语义 / 需确认的列出来不擅自改；改完留痕，区分「已修正」与「待处理」 ## 严重级定义 🔴 阻断（功能或事实错误）· 🟡 需修（一致性 / 可读性）· 💡 建议（风格偏好，可不改） ``` #### 使用步骤 1. 告诉 Agent 检查范围与镜像关系（哪些文档互为中英版本）； 2. Agent 先机械层扫描、再语义层抽查，每条问题带「文件 + 行号 + 证据片段」； 3. 按严重级处理：确定性问题 Agent 直接修正回写，需确认项列入报告留给人。 #### 预期输出 一份审计报告：一句话结论先行，问题按严重级分组，每类问题给「可 Ctrl+F 定位的短片段 + 数量」，附录给镜像配对表与扫描口径。问题状态分四类： | **分类** | **含义** | **由谁处理** | | --- | --- | --- | | 🔴 阻断 | 功能或事实错误：漏章、链接失效、命令错误，不修不能放行 | Agent 修可确定项，需判断项留给人 | | 🟡 需修 | 一致性 / 可读性问题：术语不一致、镜像缺段、版式不齐 | Agent 修正 | | 💡 建议 | 风格偏好，无既定约定的写法差异，可不改 | 人酌情 | | ✅ 已修正 | 审计时已直接修正的确定性问题（错别字、链接编码、占位行等） | Agent 回写，报告留痕 | 每条问题都带定位信息（所在章节 / 代码块序号 / `文件:行`），可直接 Ctrl+F 定位。若项目为中英双语镜像，两份文档会成对检查、成对出结论。 #### 验证 - 报告开头写明范围、口径与镜像配对方式； - 每条问题都有「文件 + 位置 + 可定位片段」，第三方能直接复现； - 已修正项与待确认项分开列，镜像文档两侧都过了一遍。 #### 常见问题 - 镜像文档为什么不能按标题字面配对？ 标题互为译文，要用路径或内容指纹配对。 - 机械层扫描就够了吗？ 不够。机械层只管可模式化的问题，漏章、数字不符、图文错配靠语义层抽查。 - 风格差异也算问题吗？ 没有既定风格约定时，写法差异最多算建议，不作阻断项。 ### 详解 2：项目复现 #### 你将完成 按一份 README / 教程 / 安装脚本，把开源项目在目标设备上 **真正跑通**，并留下可复用的过程记录。 #### 适用场景 - 开源 Demo 部署； - 教程可执行性验证； - 开发环境迁移。 #### 前置条件 - 目标项目的源码或教程文档（README / install.sh / 部署指导）； - 目标设备与访问方式（开发板 / 服务器 / 本机，及对应的 adb / ssh / 本地终端）； - **明确的验收标准**——例如某条命令正常退出、某页面可访问、日志出现某关键词。没有验收标准就无法判断「是否跑通」。 #### Skill 定义 ```markdown --- name: project-reproduction description: Use when 按 README / 教程 / install.sh 复现、部署、跑通项目。 --- ## 流程（Procedure） P0 准备：通读原文，确认验收标准，建工作区，环境快照写入执行日志 P1 按原文逐步执行：拆步骤，每步记录「原文原句 → 执行命令 → 实际输出 → 判定」，忠实原文不预改 P2 报错 → 最优路径：完整捕获报错原文，按「环境差异 → 配置问题 → 代码与文档不符」归因，一次只改一处；修复写进项目文件本身（固化，不用一次性命令绕过） P3 收尾：全量重跑关键链路 → diff → 生成报告与通俗总结 ## 产出（开始前先建输出目录） 先读我_通俗总结.md / 00_复现报告.md / 01_执行日志.md / 02_问题与修复记录.md / 03_修改后文件/ / 04_原始快照/ ## 关键纪律 - 同一分支重试 ≤2 次无进展必须换分支或暂停上报 - 别相信脚本的「成功」自述：必须验证副作用（产物文件、进程存活、日志写入） - 嵌入式板卡须在目标用户身份下复验（adb 默认 root ≠ 普通用户环境） ``` #### 使用步骤 1. 说「按教程部署 xxx」或「复现 xxx 项目」，并说明怎样算部署成功； 2. Agent 先与你确认验收标准，再按原文逐步执行，并记录每一步的实际结果； 3. 出现报错时，按 **环境差异 → 配置问题 → 代码与文档不符** 的顺序定位，一次只改一处； 4. 修复写回项目文件本身（install.sh / 配置文件 / 源码），而不是用临时命令绕过——目标是「下一次照做一次通过」。 #### 预期输出 - 先读我_通俗总结.md：面向人的总览——一句话结论、怎么用、文件地图（每次必出）； - 00_复现报告.md：主报告，结论明确——按原文通过 / 修复后通过 / 未复现及原因； - 01_执行日志.md：逐步留痕，每步的原文、命令、实际输出与判定，边做边记； - 02_问题与修复记录.md：每个报错一条，含报错原文、归因、修复位置、验证结果； - 03_修改后文件/：最终可用文件，保留原相对路径，可直接取用； - 04_原始快照/：原文副本与修改前原始文件，供 diff 对照。 #### 验证 - 按「报告 + 修改后文件」重跑一遍关键链路，确认一次通过； - 若目标设备是开发板，在 **用户默认登录的终端** 里复跑一次（而不是在提权或非交互 shell 里），确保用户照着做也能通过。 #### 常见问题 - **装到一半报网络/超时错误？** 多数属于环境差异（镜像源、代理、长连接中断）。Agent 会先做「文档声明版本 vs 实际版本」的比对表再动手。 - **脚本打印「启动成功」就算成功吗？** 不算。必须验证副作用：产物文件是否生成、进程是否存活、日志是否真的写入。 - **能不能只改设备、不改脚本？** 不推荐。修复要固化进脚本，否则换台设备还会再踩一次。 ### 详解 3：仓库审查与设计 #### 你将完成 对一个仓库做一次整体体检，或为一个新项目设计仓库文件结构。 #### 适用场景 - 开源项目发布前检查； - 技术选型评估； - 接手既有仓库时的体检； - 新项目的目录与标准文件规划。 #### 前置条件 - 仓库地址（owner/repo 或 URL）或本地路径； - gh 已认证，或已设置 GITHUB_TOKEN（用于 clone 与调用 GitHub API）； - 如需整改，需对该仓库有写权限。 #### Skill 定义 ```markdown --- name: github-repo-review-and-design description: Use when 整仓代码审查 + 仓库文件设计。 --- ## 模式判定（Step 0，共用前置） 自家 / 可写仓库 → 发布档（审查后可整改到可发布）；第三方仓库 → 评估档（只读，只给采用建议） ## Workflow A — 整仓代码审查 A1 元数据快照：语言 / 规模 / 许可证 / 活跃度 / CI 真实性 A2 结构与架构：先「宣称」后「核对」（宣称能力 vs 实际代码、教程路径 vs 真实入口、配置键 vs 代码读取） A3 分层审查：L1 入口 → L2 核心逻辑 → L3 配置/接口 → L4 工具脚本 → L5 测试/CI，每层过六维清单（正确性 / 安全 / 代码质量 / 测试 / 性能 / 文档与工程化） A4 自动化扫描：敏感信息、残留标记、大文件、依赖漏洞、LICENSE A5 报告：评估档出结论卡 + 采用建议（✅ 直接用 / 🔶 参考学习 / ❌ 放弃）；发布档出就绪度结论 + 就绪检查表 + 🔴🟡 整改清单（整改后重跑验证） ## Workflow B — 仓库文件设计 B1 定类型（开源 demo / 应用服务 / 库 SDK / 内部工具）→ B2 目录树 + 文件职责表 → B3 标准文件要点（README / LICENSE / .gitignore / install.sh / CI）→ B4 输出设计文档或直接生成骨架 ``` #### 使用步骤 1. 说「审查这个仓库 」；为新项目规划结构时说「为这个项目设计仓库结构」； 2. Agent 先判定模式，两种模式结论与动作不同（见下表）； 3. Agent 整仓扫描：仓库元信息（语言 / 规模 / 许可证 / 活跃度 / **CI 真实性**）→ 结构与入口 → 关键配置与接口 → 自动化扫描（明文密钥、内网地址、个人路径、大文件误入库、依赖漏洞审计）→ 测试与 CI 状态； 4. 按分级结论整改（仅发布档）。 | **模式** | **适用** | **行为** | | --- | --- | --- | | 发布档 | 自家 / 可写仓库 | 给出发布就绪清单，可整改到可发布 | | 评估档 | 第三方仓库 | 只读，给采用建议，不改代码 | #### 预期输出 - **评估档**：结论卡（维护活跃度 / 代码质量 / 文档上手成本 / 依赖许可风险 / 安全面 / 生态）+ 采用建议——✅ 直接用 / 🔶 参考学习并摘出要点 / ❌ 放弃及理由； - **发布档**：就绪度结论 + 就绪检查表逐项打勾 + 🔴🟡 分级整改清单； - 问题定位精确到 `文件:行`，可直接 Ctrl+F 定位。 #### 验证 - 逐条核对 🔴 项是否都能在仓库中按给定的 `文件:行` 复现； - 敏感信息类命中需 **人工复核**——示例密钥、测试夹具、占位符是常见假阳性； - CI 项以真实运行记录为准（有配置文件 ≠ 真在跑）。 #### 常见问题 - **会顺手改第三方仓库吗？** 不会。评估档严格只读，绝不会对第三方仓库建分支或提交。 - **CI 是绿色的就没问题吗？** 要区分「有配置」与「真在跑」。僵尸 CI（有 workflow 文件、运行记录为空或全失败）会被单独标出。 - **审查结果能贴到 PR 上吗？** 可以，可转到 PR 行内评论的形式。 ## 如何编写一个 Skill 新增能力不需要写代码。在 Hermes 中，一个 Skill 就是一份 `SKILL.md`，有两种写法： **方式一：让 Hermes 帮你创建（推荐）**。在对话中直接描述需求，例如「帮我创建一个 Skill，在每次 git commit 前自动跑测试和 lint，叫 pre-commit-check」，Hermes 会自动生成符合规范的 `SKILL.md` 并存入 `~/.hermes/skills/` 对应目录。 **方式二：手动编写`SKILL.md`**。在 `~/.hermes/skills/<分类>//` 下创建目录与文件。最小模板（复制即用）： ```markdown --- name: my-skill-name description: Use when <触发条件>. <一句话描述行为>. --- # 能力标题 ## Overview 一两句话：这个 Skill 做什么、为什么需要。 ## When to Use - 触发条件 1 - 触发条件 2 - 不要用在：反例 ## Steps ### Step 1：xxx 具体操作；完成条件：…… ## Common Pitfalls 常见错误与修复方法。 ## Verification Checklist - [ ] 验证项 ``` ### Skill 撰写规范 以下要求与 Agent Skills 官方规范对齐（参考 [specification]() 与 [best practices]()）： | **规范项** | **要求** | | --- | --- | | `name` | 小写字母 + 连字符，≤ 64 字符，且与技能目录名完全一致（如 `doc-consistency-audit`） | | `description` | ≤ 1024 字符；以 `Use when ...` 开头，描述一类触发条件（不是单个任务），把用户可能说出的关键词写进去 | | `SKILL.md` 长度 | 建议 ≤ 500 行 / 5000 tokens，只放每次都要用的核心流程；更长的参考资料拆到 `references/` | | `references/` 用法 | 在 SKILL.md 里写明「什么情况下读哪个文件」，让 Agent 按需加载（渐进披露） | | 文件开头 | 必须以 `---` 开头的 frontmatter 起首，前面不能有空行或 BOM | | 内容取舍 | 写 Agent 不知道的东西（项目约定、领域流程、非显而易见的边界情况），不复述通用常识 | > 自查三问：`description` 能否被一句话触发？流程里有没有「只有作者知道的隐式前提」？把技能交给别人，他能否照着走完？ ### 加载与验证 ```bash /reload-skills # 对话中执行：重新扫描 skills 目录 hermes skills list | grep my-skill-name # 确认 Skill 已安装 hermes -s my-skill-name # 新会话预加载，做触发测试 ``` > **建议**：把「什么时候用」写清楚，比把「怎么做」写长更重要。Agent 靠 description 判断是否加载 Skill——触发条件写得准，它才能在正确的时机调起这项能力。 ## 技术支持与贡献 如在使用过程中遇到问题，欢迎在 [移远官方论坛]() 提交技术咨询，我们的技术支持团队将及时为您解答。