Skill开发指南¶

💡 开源地址：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
├─ ...                               # 其余技能见「技能索引」
└─ <your-skill>/                     # 新增一项能力：加一个目录即可
   └─ SKILL.md

生效机制：每次新会话启动时，Hermes 会扫描 ~/.hermes/skills/，把每个 Skill 的 name 与 description 注入系统提示；当你的任务匹配某个 Skill 的触发条件（写在 description 里），Hermes 自动加载该 Skill 的完整内容，按其中定义的流程执行——不需要手动指定。

使用步骤：

将 Skill 目录放入 ~/.hermes/skills/（或用 hermes skills install 一键安装）；
在对话中输入 /reload-skills，或直接开启新会话，让 Hermes 感知新 Skill；
运行 hermes skills list，确认 Skill 已在列表中；
用自然语言描述意图，Hermes 自动匹配对应 Skill 并执行。

说明：除手动放置外，Hermes 还支持从 Skill Hub、URL 或 GitHub 仓库安装 Skill（hermes skills install <skill-id 或 URL>）；也可以在启动时用 hermes -s <skill-name> 预加载，或在对话中用 /skill <skill-name> 手动加载。

技能索引¶

本表是仓库当前 全部技能，技能名可点击跳转仓库目录。表中技能均为「稳定」状态，若出现试验或废弃技能会在版本号后标注。

分类含义：代码与仓库＝写代码、审仓库、发布前把关；部署与设备＝装环境、连板子、跑脚本；文档与交付＝写文档、审文档、交付留痕；环境与终端＝本机 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 定义「怎么查、怎么交付」，检查口径由内置清单决定——机械层全量扫描（脚本能查的绝不靠肉眼），语义层抽查；每条发现都带文件、位置、证据片段与严重级，第三方可复现定位。

---
name: doc-consistency-audit
description: Use when 一批文档 / 多语言镜像文档交付前做一致性审计。
---

## 流程（Procedure）
① 定范围与镜像对：列待查清单，建「中文 ↔ 英文」配对表（按路径 / 内容指纹配对，不靠标题字面）
② 机械层扫描（可脚本化优先）：链接、代码块、占位残留、术语变体、版式——命中即给「文件 + 行号 + 片段」
③ 语义层抽查：结构与宣称是否一致、数字与配置一致、镜像一致性、图文对应
④ 结果落成 findings：每条一条「文件 | 位置 | 问题类型 | 证据片段 | 严重级 | 建议」
⑤ 出报告：一句话结论 → 按严重级分组 → 每类问题给「可 Ctrl+F 定位的短片段 + 数量」

## 修复纪律（Fix Discipline）
- 确定性问题直接修（错别字、链接编码、占位行、命令粘连），边审边改不必逐条请示
- 镜像同步：改了中文版，必须同步检查 / 修改对应英文版（反之亦然）
- 语义 / 需确认的列出来不擅自改；改完留痕，区分「已修正」与「待处理」

## 严重级定义
🔴 阻断（功能或事实错误）· 🟡 需修（一致性 / 可读性）· 💡 建议（风格偏好，可不改）

使用步骤¶

告诉 Agent 检查范围与镜像关系（哪些文档互为中英版本）；
Agent 先机械层扫描、再语义层抽查，每条问题带「文件 + 行号 + 证据片段」；
按严重级处理：确定性问题 Agent 直接修正回写，需确认项列入报告留给人。

预期输出¶

一份审计报告：一句话结论先行，问题按严重级分组，每类问题给「可 Ctrl+F 定位的短片段 + 数量」，附录给镜像配对表与扫描口径。问题状态分四类：

分类	含义	由谁处理
🔴 阻断	功能或事实错误：漏章、链接失效、命令错误，不修不能放行	Agent 修可确定项，需判断项留给人
🟡 需修	一致性 / 可读性问题：术语不一致、镜像缺段、版式不齐	Agent 修正
💡 建议	风格偏好，无既定约定的写法差异，可不改	人酌情
✅ 已修正	审计时已直接修正的确定性问题（错别字、链接编码、占位行等）	Agent 回写，报告留痕

每条问题都带定位信息（所在章节 / 代码块序号 / 文件:行），可直接 Ctrl+F 定位。若项目为中英双语镜像，两份文档会成对检查、成对出结论。

验证¶

报告开头写明范围、口径与镜像配对方式；
每条问题都有「文件 + 位置 + 可定位片段」，第三方能直接复现；
已修正项与待确认项分开列，镜像文档两侧都过了一遍。

常见问题¶

镜像文档为什么不能按标题字面配对？标题互为译文，要用路径或内容指纹配对。
机械层扫描就够了吗？不够。机械层只管可模式化的问题，漏章、数字不符、图文错配靠语义层抽查。
风格差异也算问题吗？没有既定风格约定时，写法差异最多算建议，不作阻断项。

详解 2：项目复现¶

你将完成¶

按一份 README / 教程 / 安装脚本，把开源项目在目标设备上 真正跑通，并留下可复用的过程记录。

适用场景¶

开源 Demo 部署；
教程可执行性验证；
开发环境迁移。

前置条件¶

目标项目的源码或教程文档（README / install.sh / 部署指导）；
目标设备与访问方式（开发板 / 服务器 / 本机，及对应的 adb / ssh / 本地终端）；
明确的验收标准——例如某条命令正常退出、某页面可访问、日志出现某关键词。没有验收标准就无法判断「是否跑通」。

Skill 定义¶

---
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 ≠ 普通用户环境）

使用步骤¶

说「按教程部署 xxx」或「复现 xxx 项目」，并说明怎样算部署成功；
Agent 先与你确认验收标准，再按原文逐步执行，并记录每一步的实际结果；
出现报错时，按 环境差异 → 配置问题 → 代码与文档不符 的顺序定位，一次只改一处；
修复写回项目文件本身（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 定义¶

---
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 输出设计文档或直接生成骨架

使用步骤¶

说「审查这个仓库 <owner/repo 或仓库地址>」；为新项目规划结构时说「为这个项目设计仓库结构」；
Agent 先判定模式，两种模式结论与动作不同（见下表）；
Agent 整仓扫描：仓库元信息（语言 / 规模 / 许可证 / 活跃度 / CI 真实性）→ 结构与入口 → 关键配置与接口 → 自动化扫描（明文密钥、内网地址、个人路径、大文件误入库、依赖漏洞审计）→ 测试与 CI 状态；
按分级结论整改（仅发布档）。

模式	适用	行为
发布档	自家 / 可写仓库	给出发布就绪清单，可整改到可发布
评估档	第三方仓库	只读，给采用建议，不改代码

预期输出¶

评估档：结论卡（维护活跃度 / 代码质量 / 文档上手成本 / 依赖许可风险 / 安全面 / 生态）+ 采用建议——✅ 直接用 / 🔶 参考学习并摘出要点 / ❌ 放弃及理由；
发布档：就绪度结论 + 就绪检查表逐项打勾 + 🔴🟡 分级整改清单；
问题定位精确到 文件:行，可直接 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/<分类>/<skill 名>/ 下创建目录与文件。最小模板（复制即用）：

---
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 能否被一句话触发？流程里有没有「只有作者知道的隐式前提」？把技能交给别人，他能否照着走完？

加载与验证¶

/reload-skills                              # 对话中执行：重新扫描 skills 目录
hermes skills list | grep my-skill-name     # 确认 Skill 已安装
hermes -s my-skill-name                     # 新会话预加载，做触发测试

建议：把「什么时候用」写清楚，比把「怎么做」写长更重要。Agent 靠 description 判断是否加载 Skill——触发条件写得准，它才能在正确的时机调起这项能力。

技术支持与贡献¶

如在使用过程中遇到问题，欢迎在移远官方论坛提交技术咨询，我们的技术支持团队将及时为您解答。