hermes-productivity-skills

License: MIT

A Hermes agent skill tap: a small repo of productivity skills you can install into your Hermes agent. It currently ships:

  • umami-report (category analytics) — per-site visitor and pageview numbers from a private, self-hosted Umami instance.
  • superproductivity-report (category productivity) — time-tracking reports (hours per project, hours per day, tasks completed) from a Super Productivity data file.
  • obsidian-notes (category notes) — read and write notes in an Obsidian vault: list notes (all, or modified in a window), show a note, and save the current chat as a note.
  • emailops (category email) — query, search, and chat with a local EmailOps mailbox via emailops-cli.
  • calendar (category calendar) — check your Google Calendar (read-only): today / this week / upcoming events as an agenda, via the builtin google-workspace skill's OAuth.
  • git-report (category development) — your git commit activity over a window (commits per repo/day, grouped by author) across one or more repos.
  • claude-sessions (category development) — your Claude Code sessions over a window: start/duration/project/title, token usage, API-equivalent cost, and an A–D cost-efficiency grade, straight from local transcripts.
  • weekly-report (category reports) — one weekly report combining the above: time per project/task, the week's Obsidian notes (with key bullet points), emails sent this week, calendar events, commits, Claude sessions, and page visits vs last week.
analytics/
├── DESCRIPTION.md
└── umami-report/
    ├── SKILL.md                      # skill definition (frontmatter + usage)
    └── scripts/
        ├── umami_report.py           # the whole tool — Python stdlib only
        └── test_umami_report.py      # offline unit tests (no network)
productivity/
├── DESCRIPTION.md
└── superproductivity-report/
    ├── SKILL.md
    └── scripts/
        ├── sp_report.py              # the whole tool — Python stdlib only
        └── test_sp_report.py         # offline unit tests (no file/network)
notes/
├── DESCRIPTION.md
└── obsidian-notes/
    ├── SKILL.md
    └── scripts/
        ├── obsidian_notes.py        # the whole tool — Python stdlib only
        └── test_obsidian_notes.py   # offline unit tests (temp vault, no network)
email/
├── DESCRIPTION.md
└── emailops/
    └── SKILL.md                      # wraps the external `emailops-cli` (no scripts)
development/
├── DESCRIPTION.md
├── git-report/
│   ├── SKILL.md
│   └── scripts/
│       ├── git_report.py            # the whole tool — Python stdlib + system git
│       └── test_git_report.py       # offline unit tests (temp repos, no network)
└── claude-sessions/
    ├── SKILL.md
    └── scripts/
        ├── claude_sessions.py       # the whole tool — Python stdlib only
        └── test_claude_sessions.py  # offline unit tests (synthesized transcripts)
reports/
├── DESCRIPTION.md
└── weekly-report/
    ├── SKILL.md
    └── scripts/
        ├── weekly_report.py         # orchestrates the other skills — stdlib only
        └── test_weekly_report.py    # offline unit tests (children stubbed)
install-local.sh                      # symlink skills into ~/.hermes for dev

What umami-report does

Asks Umami for every website on your account and prints an aligned table of Visitors, Visits, Pageviews, Bounce% per site (plus a TOTAL row), each metric annotated with its change versus the previous equal-length period (▲/▼).

  • Fast & deterministic: zero dependencies (stdlib only), all sites fetched concurrently, UTC date math, stable JSON output (--json).
  • Secure: credentials live only in ~/.hermes/.env (mode 600) and are injected into the sandbox as env vars — never passed on a command line, never printed, never requested in chat. TLS verified by default.

Example:

Umami visits  2026-06-18 → 2026-06-25   (Δ vs previous period)

Site                  Visitors       Visits      Pageviews  Bounce%
-------------------------------------------------------------------
blog.example.com  4,415 ▲10.4%  5,680 ▲9.2%  15,171 ▲26.4%     62.8
shop.example.com    300 ▼14.3%   410 ▼14.6%     920 ▼16.4%     29.3
-------------------------------------------------------------------
TOTAL              4,715 ▲8.4%  6,090 ▲7.2%  16,091 ▲22.8%     60.5

What superproductivity-report does

Reads a Super Productivity JSON file — a backup export (sp-backup_*.json) or a local-sync sync-data.json — and answers time-tracking questions locally:

  • hours per project (projects, with --project NAME to filter),
  • hours per day (days),
  • tasks completed, grouped by project (done).

over any window (--period this-week|last-month|…, --days N, or --start/--end). Windows are local-time, Monday-start weeks; completed/archived tasks are included. Zero dependencies (stdlib only), --json for post-processing.

Time per project  2026-06-22 → 2026-06-26

Project          Time  Hours  Share
-----------------------------------
Contoso Firma  4h 30m   4.50    60%
Internal R&D   3h 00m   3.00    40%
-----------------------------------
TOTAL          7h 30m   7.50   100%

It reads one env var, SP_DATA_FILE (path to the JSON file). No credentials are sent anywhere — all computation is local. Example prompts:

how many hours did I spend on Contoso this week?
hours per day this month
list the tasks I completed this week, by project
/superproductivity-report projects --period last-month

See productivity/superproductivity-report/SKILL.md for the full command reference.

What obsidian-notes does

Reads and writes notes in an Obsidian vault — just a folder of Markdown files — over the same local-time, Monday-week windows as the report skills. Zero dependencies (stdlib only), --json everywhere.

  • list — every note, or only those modified in a window (--period this-week, --days N, --start/--end; --by created to filter on creation time instead).
  • show — print one note by name or relative path.
  • save — write a new note into the vault; the agent pipes the content in, so it can save the current chat as a note (frontmatter + body, never clobbers an existing file).

It reads one env var, OBSIDIAN_VAULT (the vault folder). All computation is local — nothing is sent anywhere. Example prompts:

what notes did I take this week?
list all my notes
show me my Ideas note
save this chat to my vault

Notes modified 2026-06-22 → 2026-06-26

Note                   Modified     Created  Size
-------------------------------------------------
Ideas.md             2026-06-26  2026-06-01   37B
Daily/2026-06-24.md  2026-06-24  2026-06-24   57B
-------------------------------------------------
2 note(s)

See notes/obsidian-notes/SKILL.md for the full command reference.

What claude-sessions does

Reads your local Claude Code transcripts (~/.claude/projects/**/*.jsonl) and answers "what Claude Code sessions did I have this week / last month / in this range — and which were expensive or wasteful?" No config, no network — it only reads files already on disk.

  • list — sessions active in a window, most expensive first by default (--sort recent for newest), full table (models, tokens, cost, an A–D cost-efficiency grade, and a per-session recommendation) or --shorten for a compact view.
  • projects — one row per project (sessions, prompts, tokens, API-eq cost).
  • efficiency — ranks sessions by cost-efficiency grade and rolls up "spend less" habits for the window.
  • find / show — locate a session by title/slug, then get a full single-session deep dive (tools used, skills/MCP invoked, files edited).

Subagent transcripts are folded into their parent session's totals, and token counts are de-duplicated to match Claude Code's own /usage. Example prompts:

what Claude sessions did I have this week?
which sessions were wasteful this month?
find that session about the calendar skill

See development/claude-sessions/SKILL.md for the full command reference.

What weekly-report does

Stitches the other skills into one weekly report. A deterministic gather step runs each of them with --json and assembles a single bundle (time per project + tasks, the week's notes with their bodies, emails sent this week, calendar events, commits, Claude Code sessions, and page visits vs last week); the agent then writes the prose — including 3–4 bullet points per note. Each source is independent: if one isn't configured, that section is skipped with a note and the rest still renders. No new env vars (it reuses SP_DATA_FILE, OBSIDIAN_VAULT, UMAMI_*, GIT_REPOS_DIR, and emailops-cli; claude-sessions needs no env var at all); the orchestrator loads ~/.hermes/.env itself so the child skills get their config even as nested subprocesses.

SCRIPT=~/.hermes/skills/reports/weekly-report/scripts/weekly_report.py
python3 $SCRIPT check                       # which of the 3 sources are ready
python3 $SCRIPT gather --period this-week    # JSON bundle the agent renders from
python3 $SCRIPT gather --text                # human-readable skeleton

Weekly report  2026-06-22 → 2026-06-26

PROJECTS & TIME
Project    Hours
----------------
Contoso    9.13h
...
TOTAL     24.64h

NOTES (modified/created this week)
  • Projects/Weekly Plan.md  (mod 2026-06-26, created 2026-06-25)
  ...
  → 3–4 bullet points per note are written by the agent from each body.

EMAILS SENT (this week)
  • 2026-06-26  Re: Project update  → [email protected]
  ...

VISITS (vs last week)
Site               Visitors   Pageviews
blog.example.com  18 ▲12.5%   21 ▲31.2%
...

Example prompts: make my weekly report, weekly review for last week. See reports/weekly-report/SKILL.md for the full reference.

Configuration (env vars)

Each skill declares its required_environment_variables. Set them once in ~/.hermes/.env — do not paste them into an agent chat:

hermes config                 # guided, or:
$EDITOR ~/.hermes/.env        # add the lines you need

# umami-report (self-hosted Umami login)
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=your-username
UMAMI_PASSWORD=your-password

# superproductivity-report (path to your SP backup/sync JSON)
SP_DATA_FILE=/Users/you/SuperProductivity/sync-data.json

# obsidian-notes (path to your Obsidian vault folder)
OBSIDIAN_VAULT=/Users/you/Obsidian/MyVault

~/.hermes/.env is private (mode 600) and is the standard place Hermes reads skill config from; values are auto-injected into the terminal sandbox.

umami-report targets self-hosted Umami (username/password login); Umami Cloud's x-umami-api-key header is not supported. superproductivity-report reads a local JSON file — if you enabled SP sync encryption, point it at an unencrypted backup export instead.

Install

Local development (this repo, live edits)

./install-local.sh            # symlinks each category into ~/.hermes/skills/
hermes skills list | grep -iE 'umami|super'

A brand-new category (analytics) is symlinked whole; for a category that already exists (e.g. the built-in productivity), each skill folder is symlinked into it without touching the built-ins. Because it symlinks, edits to the script/SKILL.md here take effect immediately.

From a published repo (others)

hermes skills tap add gerodp/hermes-productivity-skills
hermes skills install gerodp/hermes-productivity-skills/umami-report --category analytics

Usage

Through the agent (natural language or slash command):

report my website visits
/umami-report last 30 days
how many visitors did blog.example.com get this week?

Directly on the CLI:

SCRIPT=~/.hermes/skills/analytics/umami-report/scripts/umami_report.py
python3 $SCRIPT check                       # verify config + login
python3 $SCRIPT report                       # all sites, last 7 days
python3 $SCRIPT report --days 30
python3 $SCRIPT report --since today
python3 $SCRIPT report --start 2026-06-01 --end 2026-06-07
python3 $SCRIPT report --site blog
python3 $SCRIPT report --json

See analytics/umami-report/SKILL.md for the full command reference and the agent-facing instructions.

Development & testing

No build, no dependencies. Run the offline test suite (stubs the Umami API, no network):

python3 analytics/umami-report/scripts/test_umami_report.py

Then verify end-to-end against your instance with check and report as above.

License

MIT — see LICENSE.