agentleFS
TechNickAITechNickAI/hermes-skills/skills/core/report/SKILL.md

report

Skill0 starsChanged 3 months agoMITView on GitHub

File a report or piece of feedback from any Hermes platform session. Load this skill when the user says "/report", "file a bug", "report a bug", "something's broken", "something's wrong", "that's weird", "this is wrong", "this isn't working", "log this issue", or any other signal that they want to capture a problem for triage. Works on Telegram, Discord, Slack, and the CLI — the closed loop (a notification back to this chat when the issue is resolved) is wired automatically for gateway sessions.

  • Reads credentials

104 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use opportunities, export and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ansvisorSkill

    opportunities

    Finds content gaps, prompts worth tracking, and the off-site sources AI cites instead of the brand.

    Also in 3 projects that use this

  • soilmassSkill

    export

    Animation export configurations including format selection, resolution, framerate, quality, and optimization settings. Use when rendering animations for web, mobile, video, or social media. Provides tokens for all export parameters across Lottie, GIF, video, and sprite sheet formats.

    Also in 4 projects that use this

  • GoogleSkill

    quality

    Evaluates whether a GitHub issue is spam, empty, needs more information, or is OK to proceed.

    Also in 3 projects that use this

  • genomewalkerSkill

    resume

    Resume a thread by loading its ~800-token context capsule

    Also in 7 projects that use this

  • tokyubevoxelverseSkill

    checkup

    Give a repository a full health exam — doc rot, dependency staleness, CI decay, git hygiene, dead links, docs contradicting code — and grade it. Use when the user wants to know what quietly rotted, or a prioritized maintenance list.

    Also in 3 projects that use this

  • rajnavakotiSkill

    scan

    Run the AI dashboard scanner and generate the HTML report.

    Also in 5 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 5 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 76 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Gather the title: If the user's message contains a clear description, distill it into ≤10 words.

    line 47
  2. Distinctive:

    Do NOT include raw API keys, tokens, or personal credentials anywhere in the body.

    line 56
  3. Very specific:

    File the report: Prefer the helper script if it is installed with this skill (see Script Path below).

    line 58
  4. Distinctive:

    Never drop the report: If filing fails, save the markdown body to a local dropfile and tell the maintainer where it is.

    line 68
  5. Very specific:

    If the script is not found, fall back to calling hermes kanban create inline (see Fallback section below).

    line 89
  6. Very specific:

    Run this with TITLE, BODY_FILE, and REPORTER exported.

    line 150
  7. Very specific:

    After a successful ok: true result:

    line 212
  8. Distinctive:

    After a deduped result (same session within the 2-minute window, same id returned):

    line 217
  9. Distinctive:

    After a failure with dropfile:

    line 221
  10. Very specific:

    If REPORT_BOARD_OWNER is set and matches this profile → local.

    line 247
  11. Very specific:

    When the triager calls hermes kanban complete <id>, the gateway's kanban notifier automatically delivers one message to the subscribed …

    line 255
  12. Very specific:

    If the card is blocked: ⏸ Kanban...

    line 262
  13. Distinctive:

    Do not include personal credentials, API keys, or sensitive financial/health context in the body.

    line 271

“Common” is measured: kept by at least 6 in 10 of the 76 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Report

File a bug or piece of feedback, land it in the triage column of the shared kanban board, and wire a closed-loop notification so the reporter hears back when it's resolved — all from a single /report or a natural-language sentence.

When to load

Load this skill automatically when the current user turn contains any of these patterns (case-insensitive):

  • /report (exact slash-command)
  • "file a bug" / "report a bug" / "report this bug"
  • "file a report" / "file an issue" / "log this issue"
  • "something's broken" / "something is broken"
  • "something's wrong" / "something is wrong"
  • "this is broken" / "this isn't working" / "this doesn't work"
  • "that's weird" / "this is weird" / "that was weird"
  • "there's a bug" / "i found a bug"

Also load when the user explicitly says "load the report skill" or asks to file feedback or a suggestion.

What you do

  1. Acknowledge immediately. Reply with a short line so the user knows you've got it: "On it — filing that now."
  2. Gather the title. If the user's message contains a clear description, distill it into ≤10 words. If they just said /report with no detail, ask one brief question: "What's the issue in one sentence?". Do not ask for more — the transcript excerpt provides context.
  3. Build the body. Compose a markdown body with:
    • What the user reported: their exact words (quote them)
    • Session context: profile name, platform, timestamp (from env)
    • Transcript excerpt: the last 5–10 turns of the current session in condensed form (enough to let a triager reproduce or understand)
    • Do NOT include raw API keys, tokens, or personal credentials anywhere in the body.
  4. Write body to a temp file (e.g. /tmp/report-body-<session_id>.md).
  5. File the report. Prefer the helper script if it is installed with this skill (see Script Path below). If only this SKILL.md is installed, use the self-contained fallback workflow below — do not fail just because scripts/file_report.py is absent.
  6. Confirm.
    • Local path: tell the user the card id and: "You'll get a ping here when it's resolved."
    • Remote path: tell the user the report was sent to the triage board and they will get a ping when it is triaged or resolved. The remote path is asynchronous, so it may not have a card id immediately.
  7. Never drop the report. If filing fails, save the markdown body to a local dropfile and tell the maintainer where it is.

Script path

The helper lives alongside this skill. Resolve it relative to this file:

SKILL_DIR=$(dirname "$(hermes skills list --paths 2>/dev/null | grep '/report/SKILL.md' | head -1)")
SCRIPT="$SKILL_DIR/scripts/file_report.py"

Or resolve via Hermes's skills directory convention:

# The skill is installed at one of these locations:
#   ~/.hermes/skills/report/scripts/file_report.py          (single-profile install)
#   ~/.hermes/profiles/<name>/skills/*/report/scripts/file_report.py  (profile install)
SCRIPT=$(find ~/.hermes -path "*/report/scripts/file_report.py" 2>/dev/null | head -1)

If the script is not found, fall back to calling hermes kanban create inline (see Fallback section below).

Invocation

python3 "$SCRIPT" \
  --title "<10-word title you distilled>" \
  --body-file /tmp/report-body-<session_id>.md \
  --reporter "<user's display name or Telegram handle>" \
  --json

Parse stdout as JSON:

{
  "ok": true,
  "path": "local",
  "task_id": "t_a1b2c3d4",
  "status": "triage",
  "subscribed": true
}
  • ok: true → confirm to the user
  • ok: false, dropfile: "..." → post that path as a note and DM the maintainer
  • ok: false, error: "..." → use the fallback path below

Fallback (if script not found)

The fallback is self-contained so a single-file skill install still works.

Migration note: if this host still has pre-rename BUG_WEBHOOK_URL / BUG_BOARD_OWNER set but not the new REPORT_* names, do NOT fall through to the local path — that would drop the report off the shared queue. Rename the env vars to their REPORT_* equivalents first, then file.

Local fallback (no REPORT_WEBHOOK_URL configured)

hermes kanban create "<title>" \
  --triage \
  --tenant fleet-reports \
  --created-by "<reporter>" \
  --body "<condensed body>" \
  --json

Then subscribe the reporter's current chat, using fields that exist in the session env:

hermes kanban notify-subscribe <task_id> \
  --platform <HERMES_SESSION_PLATFORM> \
  --chat-id <HERMES_SESSION_CHAT_ID> \
  [--thread-id <HERMES_SESSION_THREAD_ID>] \
  [--user-id <HERMES_SESSION_USER_ID>]

Remote fallback (REPORT_WEBHOOK_URL configured)

Run this with TITLE, BODY_FILE, and REPORTER exported. It posts to the board owner using Hermes' generic webhook signature contract (X-Webhook-Signature = hex HMAC-SHA256 of the raw JSON body). The receiver is asynchronous and returns a delivery id, not a card id.

python3 - <<'PY'
import hashlib, hmac, json, os, pathlib, time, urllib.error, urllib.request

url = os.environ["REPORT_WEBHOOK_URL"]
secret = os.environ["REPORT_WEBHOOK_SECRET"]
title = os.environ["TITLE"]
body = open(os.environ["BODY_FILE"]).read()
reporter_id = (
    os.environ.get("HERMES_SESSION_ID")
    or os.environ.get("HERMES_SESSION_CHAT_ID")
    or os.environ.get("HERMES_PROFILE")
    or f"cli-{os.getpid()}"
)
bucket = int(time.time()) // 120
title_slug = hashlib.sha256(title.encode()).hexdigest()[:8]
idem_basis = f"{reporter_id}:{title_slug}:{bucket}"
idem = "report-" + hashlib.sha256(idem_basis.encode()).hexdigest()[:16]
payload = {
    "event_type": "report",
    "title": title,
    "body": body,
    "idempotency_key": idem,
    "reporter": os.environ.get("REPORTER") or os.environ.get("HERMES_SESSION_USER_NAME", "fleet-user"),
    "profile": os.environ.get("HERMES_PROFILE", ""),
    "tenant": os.environ.get("REPORT_TENANT") or "fleet-reports",
    "platform": os.environ.get("HERMES_SESSION_PLATFORM", ""),
    "chat_id": os.environ.get("HERMES_SESSION_CHAT_ID", ""),
    "thread_id": os.environ.get("HERMES_SESSION_THREAD_ID", ""),
    "user_id": os.environ.get("HERMES_SESSION_USER_ID", ""),
    "session_id": os.environ.get("HERMES_SESSION_ID", ""),
    "timestamp": int(time.time()),
}
raw = json.dumps(payload, separators=(",", ":")).encode()
sig = hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()
req = urllib.request.Request(url, data=raw, method="POST", headers={
    "content-type": "application/json",
    "X-Webhook-Signature": sig,
    "X-Idempotency-Key": idem,
})
try:
    with urllib.request.urlopen(req, timeout=15) as r:
        resp = json.loads(r.read().decode() or "{}")
    status = resp.get("status")
    if status is not None and status not in {"accepted", "delivered", "duplicate"}:
        raise RuntimeError(f"server response not accepted: {resp!r}")
    print(json.dumps({"ok": True, "path": "remote", "status": status or "accepted"}))
except (Exception, urllib.error.HTTPError) as e:
    drop = pathlib.Path("/tmp") / f"report-{idem}.json"
    drop.write_text(json.dumps({"payload": payload, "error": str(e)}, indent=2))
    print(json.dumps({"ok": False, "path": "remote", "dropfile": str(drop), "error": str(e)}))
    raise SystemExit(3)
PY

User-facing confirmation

After a successful ok: true result:

Filed as t_a1b2c3d4. I'll look into it and you'll get a ping here when it's resolved.

After a deduped result (same session within the 2-minute window, same id returned):

Already filed as t_a1b2c3d4 — no duplicate created.

After a failure with dropfile:

Couldn't reach the board right now, but your report is saved locally and I've flagged it for the maintainer. Nothing dropped.

Configuration

Set these as environment variables in your Hermes profile's dotenv file (the .env next to your profile config), or export them in the gateway's environment:

VariableRequired onPurpose
REPORT_BOARD_OWNERAll profilesProfile name that owns the triage board (required — no default ships in the template)
REPORT_WEBHOOK_URLNon-owner profilesEndpoint to POST the report to
REPORT_WEBHOOK_SECRETNon-owner profilesHMAC-SHA256 signing secret

The board-owner profile (the one where $HERMES_PROFILE matches $REPORT_BOARD_OWNER) does not need the webhook env vars — it calls hermes kanban directly. All other fleet members need both webhook vars.

How the script decides local vs remote

Routing is by capability, not by name-matching, so an unconfigured install never silently misroutes and breaks. In priority order:

  1. --force-remote / --force-local flags always win (testing / explicit control).
  2. If REPORT_BOARD_OWNER is set and matches this profile → local.
  3. Else if REPORT_WEBHOOK_URL is configured → this is a satellite → remote.
  4. Else (no webhook configured) → local. A single-host install with no webhook files directly to its own board — the safe default (worst case the report lands on this host's board rather than vanishing).

Closed-loop notification

When the triager calls hermes kanban complete <id>, the gateway's kanban notifier automatically delivers one message to the subscribed chat/thread:

✔ @<user> Kanban t_a1b2c3d4 done — <title>

If the card is blocked: ⏸ Kanban... blocked If it fails: ✖ Kanban... gave up

The subscription is removed automatically after the done notification. No polling, no manual DM required.

Privacy and data-handling notes

  • Transcript excerpts included in the report body will be visible to the triager (the maintainer). Only include turns from the session where /report was invoked.
  • Do not include personal credentials, API keys, or sensitive financial/health context in the body.
  • The fleet-reports kanban board is local (SQLite on the maintainer's machine), not cloud-synced. The webhook payload is HMAC-signed for integrity but transmitted over the network — use Tailscale or another private tunnel, not a public URL.

Triage runbook

See references/triage.md for how the maintainer handles the triage column, closes cards, and what the automatic notification message looks like.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.