AGENT SKILL

scheduled-briefing-agent

暂无简介

License 许可
Apache-2.0
最近更新
2026-10-24
Stars
★ 0
Forks
0

02 资源文件 1

03 SKILL.md 正文

scheduled-briefing-agent

Scheduled Briefing / Digest Agent

Class of work: the user wants a recurring auto-delivered brief — "daily briefing at 8am", "morning report", "ops digest", "weekly summary". Sections typically include priorities, calendar, email, news, project/repo updates, server health, and recommended next actions.

The deliverable is a cronjob (action=create) whose prompt pulls REAL data from each wired source and delivers to the user's chat. The hard part is not the cron — it's wiring each data source and handling credentials safely.

Workflow

  1. Enumerate sources BEFORE scheduling. Never schedule a brief that guesses. For each requested section, ask: where does this data live and how do I access it? Common mapping:

    Section Typical source
    Calendar / email Google Workspace (google-workspace skill) or IMAP (himalaya)
    Project updates GitHub repo(s) — gh CLI or public REST API
    Server health SSH into the host
    News (AI/tech) web_search
    Top priorities local task-list file the agent maintains
  2. Probe connectivity/auth in ONE parallel batch before promising anything: ping/SSH reachability, gh auth status, google setup.py --check, which for required binaries. Surface a status table (🟢 ready / 🟡 works-with-fix / 🔴 needs-setup) so the user sees exactly what's blocking.

  3. Wire each source, stub what's unavailable. If a source can't be reached, the brief must print "<section>: unavailable — <reason>", never fabricate. Bake that instruction into the cron prompt explicitly.

  4. Credentials: prefer keys/tokens over stored passwords (security flag). See the Security section. Ask before storing anything sensitive.

  5. Create the cron. cronjob(action=create, schedule='0 8 * * *', ...). Deliver to the origin chat (omit deliver). Make the prompt self-contained (cron runs in a fresh session with no chat context) and restrict enabled_toolsets to what it needs (e.g. web, terminal). Put the primary user-facing content in the final response — cron auto-delivers it.

  6. Format the brief clean & scannable: urgent items first, then sections with headers, tight bullets, a table where it helps. No fluff.

Security — credentials in cron jobs

  • NEVER interpolate secrets into a cron prompt — the create is BLOCKED. A prompt containing a token-in-URL fetch (e.g. curl .../bot${TELEGRAM_BOT_TOKEN}/getChat) is rejected outright by the cron guard (threat pattern 'exfil_curl_url', prompt never saved). Workaround that both passes the guard and keeps the secret out of the prompt: write a small stdlib script under ~/.hermes/scripts/ that reads the token from ~/.hermes/.env itself and prints the result; the cron prompt only says run /home/hermes/.hermes/scripts/cc_subs.py. This also survives prompt drift — the token never lives in job definitions.
  • SSH server health: do NOT store a root password in the cron prompt or memory. Generate a dedicated keypair (ssh-keygen -t ed25519 -N '' -C hermes-<purpose> -f ~/.ssh/hermes_<host>), give the user a one-liner to append the .pub to the host's authorized_keys, then SSH passwordless with -i ~/.ssh/hermes_<host>. Fallback (weaker, only if user insists): sshpass + root-only password file.
  • Confirm IPs by probing — users mistype (e.g. 192.16.1.11 vs 192.168.1.11). Test reachability before trusting the address.
  • Verify the key actually landed on the RIGHT host. A common failure: the user pastes the authorized_keys one-liner into the WRONG terminal — e.g. the Hermes CLI shell (hermes@hermes) instead of an SSH session on the Proxmox host, or onto a different box than the target IP. Symptom: SSH still returns Permission denied (publickey,password) after they say "done". Give an install command that PRINTS PROOF so you can confirm placement:
    mkdir -p /root/.ssh && chmod 700 /root/.ssh
    cat >> /root/.ssh/authorized_keys <<'EOF'
    <paste the .pub line here>
    EOF
    chmod 600 /root/.ssh/authorized_keys
    echo "keys matching:"; grep -c hermes- /root/.ssh/authorized_keys
    hostname -I   # confirms WHICH host received the key
    
    Cross-check the hostname -I output against the IP you intend to SSH to; if they differ, the key went to the wrong machine.
  • Per user rule: ask before storing anything sensitive or temporary.

Google Workspace setup quirks (bundled skill)

The bundled google-workspace skill's scripts/setup.py can vary by version:

  • Some versions do NOT accept --services / --format json. If you get unrecognized arguments, just run setup.py --auth-url bare (it emits the URL as plain stdout with a fixed scope set).
  • setup.py auto-dep-install can fail with No module named pip / Permission denied writing to system site-packages. Fix: create a uv venv and run setup.py with THAT interpreter:
    uv venv ~/.hermes/google-venv
    uv pip install --python ~/.hermes/google-venv/bin/python \
      google-api-python-client google-auth-oauthlib google-auth-httplib2
    GSETUP="~/.hermes/google-venv/bin/python ~/.hermes/skills/productivity/google-workspace/scripts/setup.py"
    
    Note: python3 -m venv may produce a venv WITHOUT pip on Debian — use uv.
  • OAuth is PKCE with redirect_uri=http://localhost:1; the browser fails to load localhost after consent — that's expected. User copies the full redirected URL back; exchange with setup.py --auth-code "<url-or-code>".
  • The redirect-grab is where users get stuck (most common failure). They paste the accounts.google.com/.../consentsummary?... page instead of the final http://localhost:1/?code=... redirect. The URL you need MUST start with localhost and contain code=. A consentsummary URL means the final Allow/Continue button (bottom of the last screen, often needs scrolling) has NOT been tapped yet. Tell them: keep tapping Continue/Allow until the address bar switches to localhost.
  • Any error on the localhost:1 page = success, whatever the text says ("can't reach", "connection refused", "address already in use", or a spinner that hangs forever). The code is already in the address bar — tell them to tap stop/✕ to end the spinner, then copy the address bar.
  • Pivot to a desktop browser after ~2 failed mobile attempts. Mobile browsers frequently hang on the localhost redirect and hide the address bar; desktop makes the localhost:1/?code=... trivial to copy. Don't loop on mobile more than twice — offer desktop early. Generate a FRESH auth-url each retry (codes/challenges are single-use and expire fast).
  • 403 access_denied while app is in Testing → add the user's email at console.cloud.google.com/auth/audience → Test users, OR publish the app. Adding a test user only unblocks the consent screen; they still must complete approval and paste the code — setup.py --check stays NOT_AUTHENTICATED until the code is exchanged.
  • invalid_request (Error 400) = redirect-URI mismatch. The redirect_uri the script sends MUST exactly match one registered on the OAuth client (scheme, host, AND port). Desktop-type clients do NOT expose an editable "Authorized redirect URIs" field in the console; a Web application client does — and setup.py accepts BOTH installed and web client JSON. Easiest resolution path that avoids repeated console edits: read what port the client actually has (from the downloaded JSON redirect_uris) and make the script match it by patching REDIRECT_URI in setup.py (a module-level constant, e.g. REDIRECT_URI = "http://localhost:8080"). Then re-run --auth-url so both the auth URL and the code exchange use the same port. Note: patching the bundled skill file can be reverted by a Hermes update — if OAuth breaks later, re-check this constant vs. the client's registered URI first.
  • After token exchange, individual Google APIs must be ENABLED in the Cloud project. A working token still returns 403 accessNotConfigured / "<API> has not been used in project N before or it is disabled" for any API not yet enabled. Enable each at console.developers.google.com/apis/api/<api>.googleapis.com/overview?project=<N> (e.g. gmail, calendar), wait ~1 min, retry. Enabling one API (Calendar) does not enable the others (Gmail) — enable each requested service.

Pitfalls

  • Scheduling before sources are wired → brief full of guesses. Enumerate first.
  • Storing plaintext root password → security hole on an exposed homelab.
  • Cron prompt referencing chat context → fails (fresh session). Self-contain it.
  • Not stubbing unavailable sources → fabricated data. Force explicit "unavailable" lines.
  • schedule='15m' creates a ONE-SHOT job (create response shows "repeat": "once"). Recurring needs 'every 15m' — check repeat/state in the create response and fix with cronjob(action=update, schedule='every 15m') before trusting it.

Script-only (no_agent) jobs — watchdog pattern

For recurring health/state watchers, skip the LLM entirely:

  • no_agent=true + script=... (relative paths resolve under ~/.hermes/scripts/).
  • The script's stdout is delivered VERBATIM on each tick; empty stdout = silent tick (nothing sent). So the script should print NOTHING when healthy and print anomalies only — a silent watchdog, no token cost. Non-zero exit sends an error alert.
  • Give the script a second --report mode that prints full stats for on-demand use.
  • Keep the script stdlib-only (it runs under the scheduler's python, not the venv); shell out to the project venv for anything heavier.
  • To run a state-changing job that must SURVIVE a service restart (e.g. verify a gateway restart), don't use a background terminal child (children die with the gateway's cgroup on KillMode=mixed); use systemd-run --user --on-active=Ns --unit=<name> <cmd> — a transient unit outside the cgroup. Verify with its own log/Telegram confirmation, since the parent session may be killed mid-turn.

04 同仓库更多 Skills