Skill Development Guide

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

💡 Repository: https://github.com/Quectel-Pi/QPi-Skills
This document introduces open-source Skills: ready-to-use Agent Skills following the Agent Skills format, covering Code & Repository, Deployment & Devices, Documentation & Delivery, Environment & Terminal, among others. These Skills are primarily based on the Quectel Pi Smart Single-Board Computer. Contributions are welcome.
Reading guide: for concepts → “What is a Skill”; to use them directly → “Skill Index” and “Skill Deep Dives”; to write your own → “How to Write a Skill”.
Prerequisite: the Hermes Agent has been deployed and configured on your device.

What is a Skill

A Skill is a unit of agent capability: a single Markdown file that states when to use it, how to do it, and what to output when done. It solidifies a successful operation into a reusable workflow instead of describing it from scratch every time.

Characteristic	Description
Zero-code extension	One .md file = one capability — no code changes or recompiling
Natural-language trigger	State your intent in one sentence — no commands or parameters to memorize
Plug and play	Drop the file into the agent’s skills directory and reload
Continuous evolution	When you hit a new problem, write the solution back into the Skill — it takes effect automatically next time

Quick Start

In Hermes, a Skill is just a directory: put a SKILL.md inside that states when to use it, how to do it, and what to output when done, optionally with auxiliary files such as references/ and scripts/. All skills live under ~/.hermes/skills/:

~/.hermes/skills/
├─ doc-consistency-audit/            # documentation consistency audit
│  └─ SKILL.md
├─ project-reproduction/             # project reproduction and deployment troubleshooting
│  └─ SKILL.md
├─ github-repo-review-and-design/    # whole-repo review and repository design
│  └─ SKILL.md
├─ ...                               # see the Skill Index for the rest
└─ <your-skill>/                     # adding a capability: just add a directory
   └─ SKILL.md

How it takes effect: every time a new session starts, Hermes scans ~/.hermes/skills/ and injects each Skill’s name and description into the system prompt; when your task matches a Skill’s trigger conditions (written in its description), Hermes automatically loads the full Skill content and follows the workflow defined in it — no manual selection needed.

Usage steps:

1. Put the Skill directory into ~/.hermes/skills/ (or install it in one shot with hermes skills install);

2. Type /reload-skills in the conversation, or simply start a new session, so Hermes picks up the new Skill;

3. Run hermes skills list and confirm the Skill is in the list;

4. Describe your intent in natural language — Hermes matches the corresponding Skill and executes it automatically.

Note: besides manual placement, Hermes can install Skills from the Skill Hub, a URL, or a GitHub repository (hermes skills install <skill-id or URL>); you can also preload at startup with hermes -s <skill-name>, or load manually in the conversation with /skill <skill-name>.

Skill Index

This table lists all skills currently in the repository; skill names link to the repository directory. All skills listed are in a “stable” state — experimental or deprecated skills are marked after the version number.

Category meanings: Code & Repository = writing code, reviewing repositories, pre-release gatekeeping; Deployment & Devices = setting up environments, connecting boards, running scripts; Documentation & Delivery = writing docs, reviewing docs, keeping a delivery trail; Environment & Terminal = local shell and platform differences.

Skill	Version	Category	One-liner	Typical trigger
code-authoring	0.1.0	Code & Repository	Comments only say “why” + minimal sufficient changes, keeping diffs reviewable	Before writing a new feature or modifying someone else’s code
github-repo-review-and-design	0.1.0	Code & Repository	Whole-repo graded review (assessment / release) + directory-structure design for new projects	“Is this repo worth using?”
prepublish-repo-audit	0.1.0	Code & Repository	The gate before open-sourcing or delivery: visibility, secrets, internal identifiers, repo hygiene	“Can this repo go public?”
project-reproduction	0.1.0	Deployment & Devices	Reproduce / deploy per the tutorial; fix errors along the cheapest path and make fixes permanent in files	“Reproduce / deploy / get this running per the tutorial”
shell-script-hardening	0.1.0	Deployment & Devices	Install and deploy scripts that are idempotent, diagnosable on failure, and honest about success	Writing or fixing a one-click install script
adb-device-toolkit	0.1.0	Deployment & Devices	adb device recognition, knowing which identity you run as, two-sided file-transfer checksums, long tasks detached from the session	Connecting a dev board / debugging an Android device
windows-shell-tooling	0.1.0	Environment & Terminal	Path / line-ending / encoding / file-writing pitfalls on Windows + git-bash	A command misbehaves in git-bash
feishu-docs-api	0.1.0	Documentation & Delivery	Write / sync / archive Feishu (Lark) cloud docs (docx / wiki / Bitable) via REST	“Edit this Feishu doc”, “Sync this md to the cloud”
doc-consistency-audit	0.1.0	Documentation & Delivery	Consistency check for a batch of docs / multi-language mirrors + graded report	“Audit this batch of docs”
deliverable-pack	0.1.0	Documentation & Delivery	Distill one-off work into a reviewable five-piece deliverable pack	Handover after a reproduction, migration, or research task

How to Get

• Repository: https://github.com/Quectel-Pi/QPi-Skills

• Clone and copy the skills you need into your agent’s skills directory: git clone https://github.com/Quectel-Pi/QPi-Skills.git, then cp -r QPi-Skills/skills/* ~/.hermes/skills/

• Hermes users can also subscribe: hermes skills tap add Quectel-Pi/QPi-Skills

• Other clients supporting the Agent Skills format: npx skills add Quectel-Pi/QPi-Skills

Tip: every skill is a self-contained SKILL.md — take what you need; skills keep evolving with the workflow, and version numbers follow the repository README.

Skill Deep Dives

The three sections below cover the most representative skills in the repository: doc-consistency-audit (documentation consistency audit), project-reproduction (project reproduction), and github-repo-review-and-design (whole-repo review and repository design). Each section extracts only the key points of the definition — the full definition lives in the SKILL.md inside the repository.

Deep Dive 1: Documentation Consistency Audit

What You Will Accomplish

Hand the agent a batch of documents (a directory tree, a knowledge base, a product line) or a Chinese-English mirror doc tree, and get back a reproducible consistency-audit report: the mechanical layer scans links / code blocks / leftover placeholders / terminology / formatting, the semantic layer samples for missing chapters and number mismatches, and issues are output by severity with location info; unambiguous problems are fixed on the spot and written back.

When to Use

• Pre-delivery checks on a batch of documents (a directory tree, a knowledge base, a product line);

• Chinese-English (or multi-language) mirror doc trees: confirm whether both sides are in sync and whether anything is untranslated;

• Pre-release documentation regression: leftover placeholders, TODOs, dead links, broken code blocks.

Prerequisites

• A defined scope and mirror relations (which documents are the same content in another language);

• Access to the doc sources: local markdown, a repository, or a platform API all work (the mechanical layer only needs plain text).

Skill Definition

Rules and workflow in one: the Skill defines how to check and how to deliver, while the checking criteria come from built-in checklists — a full scan at the mechanical layer (anything a script can check is never eyeballed), sampling at the semantic layer; every finding carries file, location, evidence snippet, and severity, reproducible and locatable by a third party.

---
name: doc-consistency-audit
description: Use when auditing a batch of documents / a multi-language doc tree for consistency before delivery.
---

## Procedure
① Define scope and mirror pairs: list the documents to check; build the "CN ↔ EN" pairing table (pair by path / content fingerprint, never by literal title)
② Mechanical scan (scriptable first): links, code blocks, leftover placeholders, terminology variants, formatting — every hit yields "file + line + snippet"
③ Semantic sampling: structure vs claims, numbers vs configs, mirror consistency, text-figure correspondence
④ Record findings: one row per issue — "file | location | type | evidence snippet | severity | suggestion"
⑤ Write the report: one-sentence conclusion → grouped by severity → per issue type, a "Ctrl+F-able short snippet + count"

## Fix Discipline
- Fix unambiguous problems directly (typos, link encoding, leftover placeholders, glued commands) — no need to ask per item
- Keep mirrors in step: whenever the Chinese side changes, check / update the English counterpart (and vice versa)
- Semantic / needs-confirmation items are listed, never silently changed; leave a trail, separating "fixed" from "outstanding"

## Severity Levels
🔴 blocking (functional or factual error) · 🟡 should fix (consistency / readability) · 💡 suggestion (style preference, optional)

Usage Steps

1. Tell the agent the scope and mirror relations (which documents are each other’s CN/EN versions);

2. The agent runs the mechanical scan first, then semantic sampling — every issue carries “file + line + evidence snippet”;

3. Handle by severity: the agent fixes unambiguous problems directly and writes them back; items needing confirmation go into the report for humans.

Expected Output

One audit report: a one-sentence conclusion first, issues grouped by severity, each issue type given a “Ctrl+F-able short snippet + count”, with the mirror-pairing table and scan criteria in the appendix. Issue status falls into four categories:

Category	Meaning	Handled by
🔴 Blocking	Functional or factual errors: missing chapters, dead links, broken commands — cannot ship without fixing	The agent fixes unambiguous items; judgment calls go to humans
🟡 Should fix	Consistency / readability issues: inconsistent terminology, missing mirror passages, uneven formatting	The agent fixes
💡 Suggestion	Style preferences; wording differences where no convention exists — fine to leave alone	Human discretion
✅ Fixed	Unambiguous problems already fixed during the audit (typos, link encoding, leftover placeholders, etc.)	Written back by the agent, with a trail in the report

Every finding carries location info (section / code-block number / file:line) so you can jump straight to it with Ctrl+F. If the project is a CN-EN bilingual mirror, the two documents are checked in pairs and conclusions come out in pairs.

Verification

• The report states the scope, criteria, and mirror-pairing method up front;

• Every finding carries “file + location + locatable snippet”, directly reproducible by a third party;

• Fixed items and to-confirm items are listed separately; both sides of every mirror pair have been checked.

FAQ

• Why can’t mirrored docs be paired by literal title? Titles are translations of each other — pair by path or content fingerprint.

• Is the mechanical scan enough? No. The mechanical layer only covers patternable problems; missing chapters, number mismatches, and text-figure mismatches rely on semantic sampling.

• Are style differences problems too? Without an agreed style guide, a wording difference is at most a suggestion, never a blocking item.

Deep Dive 2: Project Reproduction

What You Will Accomplish

Following a README / tutorial / install script, actually get an open-source project running on the target device, leaving behind a reusable record of the process.

When to Use

• Deploying an open-source demo;

• Verifying that a tutorial is executable;

• Migrating a development environment.

Prerequisites

• The target project’s source code or tutorial documents (README / install.sh / deployment guide);

• The target device and how to access it (dev board / server / local machine, and the corresponding adb / ssh / local terminal);

• Explicit acceptance criteria — e.g., a certain command exits normally, a certain page is reachable, a certain keyword appears in the logs. Without acceptance criteria there is no way to judge “running or not”.

Skill Definition

---
name: project-reproduction
description: Use when reproducing, deploying, or getting a project running per its README / tutorial / install.sh.
---

## Procedure
P0 Prepare: read the source document in full, confirm the acceptance criteria, create the workspace, write the environment snapshot into the execution log
P1 Execute the documented steps faithfully: break down the steps; record per step "source quote → command run → actual output → verdict"; stay faithful to the source, no preemptive edits
P2 Errors → cheapest path: capture the full raw error text; root-cause in the order "environment mismatch → configuration → code-vs-docs mismatch"; change one thing at a time; write fixes into the project files themselves (make them permanent — never bypass with one-off commands)
P3 Wrap up: re-run the whole critical path → diff → produce the report and a plain-language overview

## Outputs (create the output directory before starting)
README-FIRST-overview.md / 00_reproduction-report.md / 01_execution-log.md /
02_problems-and-fixes.md / 03_fixed-files/ / 04_baseline-snapshot/

## Key Discipline
- Stop-loss: ≤ 2 retries on the same branch with no progress → switch branches or report upward
- Never trust a script's own "success" claim: verify side effects (artifact files, process liveness, log writes)
- Embedded boards must be re-verified under the target user identity (adb defaults to root ≠ the normal-user environment)

Usage Steps

1. Say “deploy xxx per the tutorial” or “reproduce project xxx”, and state what counts as a successful deployment;

2. The agent confirms the acceptance criteria with you first, then executes the documented steps one by one, recording the actual result of each step;

3. When an error occurs, locate the root cause in the order environment mismatch → configuration → code-vs-docs mismatch, changing one thing at a time;

4. Write fixes back into the project files themselves (install.sh / config files / source code) instead of bypassing them with temporary commands — the goal is “next time, following the docs passes in one go”.

Expected Output

• README-FIRST-overview.md: the human-facing overview — a one-sentence conclusion, how to use it, the file map (always produced);

• 00_reproduction-report.md: the main report with an explicit conclusion — passed as documented / passed after fixes / not reproduced, and why;

• 01_execution-log.md: the step-by-step trail — each step’s source quote, command, actual output, and verdict, appended as you go;

• 02_problems-and-fixes.md: one record per error — raw error text, root cause, where the fix was made, verification result;

• 03_fixed-files/: the final usable files, original relative paths kept, ready to take and use;

• 04_baseline-snapshot/: copies of the original documents and the pre-change files, for diffing.

Verification

• Re-run the critical path once following “report + fixed files” and confirm it passes in one go;

• If the target device is a dev board, re-run it once in the terminal the user logs into by default (not in an elevated or non-interactive shell), to make sure users following the same steps also pass.

FAQ

• Network/timeout errors mid-install? Most are environment mismatches (mirror sources, proxies, long-connection drops). The agent first builds a “documented version vs actual version” comparison table, then proceeds.

• If a script prints “started successfully”, is it a success? No. Verify the side effects: artifact files generated, process alive, logs actually written.

• Can I change only the device and not the script? Not recommended. Fixes must be made permanent in the script, otherwise the same trap waits on the next device.

Deep Dive 3: Repository Review and Design

What You Will Accomplish

Give a repository a full health check, or design the repository file structure for a new project.

When to Use

• Pre-release checks on an open-source project;

• Evaluating a technology choice;

• A health check when taking over an existing repository;

• Planning the directories and standard files for a new project.

Prerequisites

• The repository address (owner/repo or URL) or a local path;

• gh authenticated, or GITHUB_TOKEN set (for cloning and GitHub API calls);

• Write access to the repository if fixes are required.

Skill Definition

---
name: github-repo-review-and-design
description: Use when performing a whole-repo code review + repository file design.
---

## Mode Decision (Step 0, shared preamble)
Your own / writable repo → release mode (fix up to a publishable state after review); third-party repo → assessment mode (read-only, adoption advice only)

## Workflow A — Whole-Repo Code Review
A1 Metadata snapshot: language / size / license / activity / CI authenticity
A2 Structure and architecture: "claims first, then verify" (claimed capabilities vs actual code, tutorial paths vs real entry points, config keys vs what the code reads)
A3 Layered review: L1 entry → L2 core logic → L3 config/interfaces → L4 utility scripts → L5 tests/CI; each layer passes the six-dimension checklist (correctness / security / code quality / tests / performance / docs & engineering)
A4 Automated scans: sensitive data, leftover markers, large files, dependency vulnerabilities, LICENSE
A5 Report: assessment mode emits a conclusion card + adoption advice (✅ use directly / 🔶 learn from it / ❌ drop it); release mode emits a readiness verdict + readiness checklist + a 🔴🟡 fix list (re-run verification after fixes)

## Workflow B — Repository File Design
B1 Decide the type (open-source demo / app service / library SDK / internal tool) → B2 directory tree + file-responsibility table →
B3 key points of the standard files (README / LICENSE / .gitignore / install.sh / CI) → B4 output a design document or scaffold directly

Usage Steps

1. Say “review this repository <owner/repo or URL>”; to plan a new project’s structure, say “design a repository structure for this project”;

2. The agent decides the mode first — the conclusions and actions differ between the two modes (see the table below);

3. The agent scans the whole repository: repository metadata (language / size / license / activity / CI authenticity) → structure and entry points → key configs and interfaces → automated scans (plaintext secrets, intranet addresses, personal paths, large files committed by mistake, dependency vulnerability audit) → tests and CI status;

4. Fix issues along the graded conclusions (release mode only).

Mode	For	Behavior
Release	Your own / writable repository	Emits a release-readiness checklist; can be fixed up to a publishable state
Assessment	Third-party repository	Read-only; gives adoption advice; never modifies code

Expected Output

• Assessment mode: a conclusion card (maintenance activity / code quality / documentation onboarding cost / dependency-license risk / security surface / ecosystem) + adoption advice — ✅ use directly / 🔶 learn from it and extract the key points / ❌ drop it, with reasons;

• Release mode: a readiness verdict + a readiness checklist with each item ticked + a 🔴🟡 graded fix list;

• Issue locations precise to file:line, directly jumpable with Ctrl+F.

Verification

• Check one by one that every 🔴 item can be reproduced in the repository at the given file:line;

• Sensitive-data hits require manual review — sample keys, test fixtures, and placeholders are common false positives;

• CI items are judged by real run records (a config file existing ≠ actually running).

FAQ

• Will you modify a third-party repo while you’re there? No. Assessment mode is strictly read-only — never branches or commits on a third-party repository.

• If CI is green, is everything fine? Distinguish “has a config” from “actually runs”. Zombie CI (workflow files present, run records empty or all failing) is flagged separately.

• Can the review results be posted onto a PR? Yes — they can be converted into inline PR comments.

How to Write a Skill

Adding a capability requires no code. In Hermes, a Skill is just a SKILL.md, and there are two ways to write one:

Option 1: Let Hermes create it for you (recommended). Describe your need directly in the conversation — e.g., “Create a Skill called pre-commit-check that automatically runs tests and lint before every git commit” — and Hermes generates a spec-compliant SKILL.md and saves it to the corresponding directory under ~/.hermes/skills/.

**Option 2: WriteSKILL.md**by hand. Create the directory and file under ~/.hermes/skills//<skill-name>/. Minimal template (copy and use):

---
name: my-skill-name
description: Use when <trigger condition>. <one-sentence behavior>.
---

# Capability Title

## Overview
One or two sentences: what this Skill does and why it is needed.

## When to Use
- Trigger condition 1
- Trigger condition 2
- Not for: counter-examples

## Steps
### Step 1: xxx
Concrete actions; done when: ...

## Common Pitfalls
Common mistakes and how to fix them.

## Verification Checklist
- [ ] Verification item

Skill Writing Standards

The requirements below are aligned with the official Agent Skills specification (see the specification and best practices):

Item	Requirement
name	Lowercase letters + hyphens, ≤ 64 characters, exactly matching the skill directory name (e.g., doc-consistency-audit)
description	≤ 1024 characters; starts with Use when ... and describes a class of trigger conditions (not a single task); include the keywords users are likely to say
SKILL.md length	Recommended ≤ 500 lines / 5000 tokens; keep only the core workflow needed every run, and split longer reference material into references/
references/ usage	State in SKILL.md “which file to read under which condition”, letting the agent load on demand (progressive disclosure)
File opening	Must start with frontmatter opened by ---; no leading blank line or BOM
Content selection	Write what the agent does not already know (project conventions, domain workflows, non-obvious edge cases); do not restate common knowledge

Three self-check questions: Can the description be triggered by one sentence? Does the workflow contain “implicit preconditions only the author knows”? If you hand the skill to someone else, can they follow it through to the end?

Loading and Verification

/reload-skills                              # run in the conversation: rescan the skills directory
hermes skills list | grep my-skill-name     # confirm the Skill is installed
hermes -s my-skill-name                     # preload in a new session for a trigger test

Advice: writing “when to use it” clearly matters more than writing “how to do it” at length. The agent decides whether to load a Skill by its description — only accurate trigger conditions let it invoke the capability at the right moment.

Technical Support and Contributions

If you run into any issues while using these skills, feel free to submit your questions on the Quectel official forum — our technical support team will be happy to help.