hermes-productivity-skills: Instructions file for Claude Code

CLAUDE.md — working in this Hermes skills tap

This repo is a Hermes agent skill tap: a collection of skills installed into a local Hermes agent. Each skill is a self-contained, stdlib-only tool the agent drives from the terminal.

Layout & conventions

<category>/
├── DESCRIPTION.md            # one-line category blurb (frontmatter `description:`)
└── <skill-name>/
    ├── SKILL.md              # frontmatter + agent-facing usage reference
    └── scripts/
        ├── <skill>.py        # the whole tool — Python stdlib ONLY (no deps)
        └── test_<skill>.py    # offline unit tests (no network, no shared state)

Conventions every skill follows — match them when adding or editing one:

• Stdlib only. No third-party packages. It must run under whatever Python the Hermes sandbox provides.
• --json everywhere. Every reporting command supports --json; the human table output is never the contract.
• A check subcommand that verifies config/connectivity and prints no secrets.
• User-facing error class (e.g. SPError, ObsidianError, WeeklyError) whose messages are safe to print — never leak secrets.
• Shared window vocabulary: local-time, Monday-start weeks via a copied compute_range(today, period=…, days=…, start=…, end=…); precedence --start/--end > --days > --period; current periods capped at today.
• Config via ~/.hermes/.env (declared in SKILL.md required_environment_variables). Never paste secrets into chat; never put them on a command line (use the child process environment instead).
• Offline tests live next to the script and stub all I/O (subprocess, network, filesystem via tempdirs). Run them before and after every change.

Security conventions (from the 2026-07 review — hold the line)

External data is attacker-influenced: emails, calendar invites, commit subjects/authors, synced note contents/filenames, tracker-synced task titles, transcript-derived titles. Whenever such text flows through a skill: