You (the agent) perform the whole cycle by following this document: discover the
most recent HKEXnews "Daily Targeted Leverage Factor" announcement(s) for L&I
products, download and read their PDFs, extract each product's daily targeted
leverage factor, then emit a human-readable Telegram digest — product rows in a
monospace code block, grouped by applicable date, with source URLs below as your
final message. You do
not route or send it — OpenClaw delivers your output (a scheduled job's announce
routing). This skill contains no channel and no credentials.
Tools used: curl, jq, pdftotext (poppler-utils), coreutils (date, sort,
awk, sed, mv, rm). python3 is used only as a PDF-text fallback when
pdftotext is absent (see scripts/pdf_to_text.py).
Design principles (why it is built this way)
Agent-native extraction. The factor table is read by you from the PDF text,
using the heuristics below — not by brittle fixed-offset parsing. HKEX wording
drifts; your reasoning absorbs that.
Structured metadata + PDF prose, combined. The HKEXnews search record gives
the authoritative stock_code ↔ short_name pairs; the PDF gives the applicable
trading date and each product's factor. You join them.
Copyright-safe. PDFs are downloaded for the current run only and every file
in the scratch dir is deleted at the end. Only the extracted factor digest survives.
Portable / no hard-coding. All URLs, the endpoint, the headline keyword, the
category gate, and the scratch dir live in one config block — never scattered
through the steps. No user-specific paths, no credentials.
Storage & config — RESOLVE THIS FIRST
All reads/writes happen in one writable, per-user home directory, never in the
skill's install folder (which may be read-only and is not reliably discoverable
from a shell). Resolve the SAME paths at the start of every action (run, setup,
doctor) with this exact block:
bash
HOME_DIR="${HKEX_LI_MONITOR_HOME:-$HOME_DIR_DEFAULT}"
mkdir -p "$HOME_DIR"
CFG="$HOME_DIR/config.json" # settings (created at setup; falls back to skill's config.example.json)
$HKEX_LI_MONITOR_HOME overrides the location; else it defaults to
~/.config/hkex-li-daily-factor-monitor (or $HOME/.config/... on most systems),
writable on any machine and surviving reinstalls.
The scratch dir for PDFs comes from config.tmp_dir (default
/tmp/hkex_li_daily_factor_monitor). If /tmp is locked down, set tmp_dir to
"$HOME_DIR/work". Everything in the scratch dir is deleted at end of run.
Do not use $0/dirname to find paths, and do not write in the skill
folder.
Config schema
Full annotated reference: config.example.json in the skill folder. Schema:
Load config, falling back to the skill's example copy if the user hasn't run setup:
bash
if [ -f "$CFG" ]; then SRC="$CFG"; else SRC="config.example.json"; fi # example is a valid, working default
BASE=$(jq -r '.hkex_base_url' "$SRC")
EP=$(jq -r '.hkex_search_endpoint' "$SRC")
KW=$(jq -r '.headline_keyword' "$SRC")
CAT=$(jq -r '.category_keyword' "$SRC")
PTYPE=$(jq -r '.product_type' "$SRC")
DAYS=$(jq -r '.days_back // 7' "$SRC")
RUNMODE=$(jq -r '.run_mode // "latest"' "$SRC")
TMP=$(jq -r '.tmp_dir' "$SRC")
UA=$(jq -r '.user_agent' "$SRC")
QS=$(jq -r '.hkex_search_params | to_entries | map("\(.key)=\(.value)") | join("&")' "$SRC")
Run-time overrides (optional): the invoking message may set days_back or
run_mode (latest | all); prefer those over config when present.
READINESS CHECK (run once on a new machine, and as doctor)
Report PASS / FAIL for each; if anything required is missing, stop and return a
clear error listing exactly what is missing — do not attempt a partial run.
bash
# 1. Required tools
for t in curl jq; do command -v "$t" >/dev/null || echo "FAIL: missing required tool '$t'"; done
# 2. PDF text: pdftotext preferred; python3 fallback acceptable
if command -v pdftotext >/dev/null; then echo "PASS: pdftotext"; \
elif command -v python3 >/dev/null; then echo "PASS: python3 fallback (scripts/pdf_to_text.py)"; \
else echo "FAIL: need pdftotext (poppler-utils) OR python3 for PDF text extraction"; fi
# 3. Outbound HTTPS connectivity
curl -sS -o /dev/null -m 20 -A "$UA" -w "hkexnews: HTTP %{http_code}\n" https://www1.hkexnews.hk/ \
|| echo "FAIL: cannot reach https://www1.hkexnews.hk"
curl -sS -o /dev/null -m 20 -A "$UA" -w "sfc: HTTP %{http_code}\n" https://apps.sfc.hk/ \
|| echo "WARN: cannot reach https://apps.sfc.hk (not needed today; reserved for future extension)"
# 4. Writable home + scratch
( : > "$HOME_DIR/.wtest" && rm -f "$HOME_DIR/.wtest" ) || echo "FAIL: $HOME_DIR not writable (set HKEX_LI_MONITOR_HOME)"
mkdir -p "$TMP" 2>/dev/null && ( : > "$TMP/.wtest" && rm -f "$TMP/.wtest" ) || echo "FAIL: tmp_dir '$TMP' not writable (set config.tmp_dir)"
A 30x/200 from hkexnews counts as reachable. apps.sfc.hk is a soft check kept
for a possible future SFC cross-reference; its failure is a WARN, not a FAIL.
PROCEDURE — one run
Step 1 — Resolve storage & load config
Run the storage block and the config-load block above. Then prepare a clean
scratch dir and register cleanup so PDFs are removed even if a later step fails:
Step 2 — Discover the latest relevant announcement(s)
Query a recent date window (not the servlet's title= param — free text there
returns 0 because it expects exact document-type codes), then filter the returned
records client-side on the headline keyword AND the CIS category. This is resilient
to HKEX category-code drift.
Empty result → explicit error (do not emit an empty digest):
bash
if [ ! -s "$TMP/matches.tsv" ]; then
rm -f "$TMP"/*.pdf 2>/dev/null
echo "No Daily Targeted Leverage Factor announcements found in the recent HKEXnews window under OTHERS (FUNDS, ETC)." >&2
exit 1
fi
run_mode selection:
latest (default): keep, for each distinct set of stock codes (col 3), only
the newest-dated row. Different managers/product families each publish their own
announcement daily, so "latest" = the newest factor for every product currently
publishing, not literally one file. De-dup:
bash
Then you read "$FN.txt" and extract, per the heuristics below.
Extraction heuristics (you do this — reason over the text)
These are documented assumptions; apply judgement, don't hard-match positions.
Applicable trading date — take it from the PDF prose, NOT by assuming "next
day". Look for: applicable for <D Month YYYY> / applicable for the <D Month YYYY> (e.g. "applicable for 10 August 2026"). Convert to ISO YYYY-MM-DD
(→ 2026-08-10). This date applies to every product in that PDF. If two dates
appear, use the one attached to "Daily targeted leverage factor ... applicable
for".
Product → stock code(s) — the header lists each product with its code(s):
text
A product may have two counters (USD + HKD) → two stock codes that share the
same factor. Some products have a single counter.
Product → factor — a table maps each product name to a factor written as
2x, -2x, 1.5x, -1x, etc. Parse to a signed decimal: 2x → 2.0,
-2x → -2.0, 1.5x → 1.5. Layout may wrap a long product name across lines
with the factor on the right — match by product name, not line number.
stock_code → short_name — take these pairs from the announcement METADATA
(the CODES and NAMES|-lists from Step 2, positionally aligned), which is
authoritative. Cross-check that every metadata code appears in the PDF header;
note (but don't fail on) any mismatch. Zero-pad codes to 5 digits as HKEX does
(7347 → 07347).
Emit one record per stock_code (so USD and HKD counters are separate rows
sharing the product's factor). Set product_type from config ("L&I").
If you locate the announcement and its date but genuinely cannot resolve a
factor for a code, that is a parse failure — raise an explicit error naming
the PDF URL and the failing code (Step: pattern-extraction); do not silently
drop it.
Step 4 — Note the fields you extracted (in your head — no JSON)
Do NOT emit JSON. The only output of this skill is the Telegram digest in
Step 5. Just keep track of these facts per stock code so you can render that digest:
stock_code — 5-digit HKEX code (e.g. 07347).
short_name — from the announcement metadata (e.g. XL2CSOPSMSN-U).
targeted_leverage_factor — signed decimal, at least one decimal place
(2.0, -1.0, 1.5, -2.0); Step 5 renders it as 2.0x / -2.0x.
date — ISO trading date the factor applies to (from the PDF).
source_pdf_url — absolute; listed in the Step 5 Sources block per announcement.
announcement_timestamp — the record's DATE_TIME, Hong Kong time.
Also hold run_mode and the count of announcements/products for the header line.
There is no structured-payload output and no downstream JSON consumer — a raw JSON
dump in the channel is a mistake, not an acceptable alternative to the digest.
The channel is Telegram. Emit a plain-text digest with the product rows inside a
code block so columns stay aligned (Telegram renders code blocks in a
monospace font; it does NOT render pipe tables or <details>). Put source URLs
below the code block as plain lines — links inside a code block are not
clickable. Emit exactly this shape, nothing before the title:
One row per short name — group stock codes by short_name. A product's HKD
and USD counters can share one short name; when they do, put every code for that
name on the one row, comma-separated in the trailing codes column
(e.g. XL2CSOPSMSN 2.0x 07747, 09747). All codes under one short name carry
the same factor.
One code block for all rows. Inside it, group by applicable date: a
Applicable <date> header line, its rows, then a blank line before the next date.
Sort date groups ascending.
Sort rows by stock code, smallest first. Order the rows within a date by each
name's smallest stock code (its reference code). So 07347 precedes 07709,
and a 09xxx-only name sorts after the 07xxx names. (Rows are name-led for
readability, but the order is by code — easy to scan to a code.)
Narrow-friendly columns (monospace):<short_name> <factor> <codes> — no
leading space; short_name left-justified padded to the width of the longest
short name in the run, two spaces, factor right-justified (width 6) so signs
line up, two spaces, the code(s). Keep lines short (≈26 chars for a single code)
so they fit a phone without horizontal scrolling; pad with spaces only, no tabs.
Factor: number with sign + x suffix — 2.0x, -2.0x, 1.5x. Keep the
.0. Use a plain hyphen - for the minus (renders reliably in Telegram mono).
Header line:N = count of announcements, M = total products (count every
stock code, so a 2-code name counts as 2). Timestamp in Hong Kong time.
Sources block: one bullet per distinct announcement PDF (its applicable date
→ absolute URL), placed after the code block so the URLs are tappable and can
wrap (URLs inside a code block are neither).
Size guard (Telegram 4096-char limit): a normal run (tens of products) fits
easily. If the digest would exceed ~3900 chars, split into one message per
Applicable <date> section (each its own titled code block) rather than
truncating — never cut a message mid-table.
Quiet is impossible here — with no matches you already exited via ERROR
HANDLING; you never reach Step 5 with an empty result.
Step 6 — Cleanup & exit
Delete all downloaded PDFs and extracted text; retain nothing (copyright):
The EXIT trap from Step 1 also removes PDFs if the run aborted early.
ERROR HANDLING (explicit, never silent)
The user prefers loud failures over quiet gaps.
No matches in window → error string (verbatim):
No Daily Targeted Leverage Factor announcements found in the recent HKEXnews window under OTHERS (FUNDS, ETC).
PDF failure → error naming the PDF URL and which step failed:
download (HTTP/empty), parse (pdftotext/python failed or empty text), or
pattern-extraction (found the doc but couldn't resolve a factor/date/code).
Discovery request failure (non-200 / non-JSON) → error naming the endpoint
and HTTP code.
On any error, still run the PDF cleanup, then exit non-zero. Do not emit a
partial/empty digest as if it were a successful result.
PROCEDURE — setup (agent-led)
Resolve $HOME_DIR, prove it is writable, and tell the user the exact path
where config/state will live.
Write $HOME_DIR/config.json from the schema atomically (write
config.json.tmp, then mv). Seed it from config.example.json.
Offer to install the schedule (below); confirm before creating.
PROCEDURE — schedule
Create a daily OpenClaw cron job. L&I flexible-leverage managers publish the next
trading day's factor after market close, so an evening HKT run (e.g. ~18:30) picks
up that day's file. Embed the resolved home path so every scheduled run uses the
same location:
bash
HOME_DIR="${HKEX_LI_MONITOR_HOME:-$HOME/.config/hkex-li-daily-factor-monitor}"
openclaw cron add \
--name hkex-li-daily-factor-monitor \
--description "Daily HKEX L&I targeted leverage factor digest" \
--cron "30 18 * * 1-5" \
--tz "Asia/Hong_Kong" \
--tools exec \
--announce \
--message "Run the hkex-li-daily-factor-monitor skill now: perform one run exactly as its SKILL.md describes (run_mode=latest), and output the Telegram monospace digest (rows grouped by applicable date, source links below) as your final message."
Delivery/routing is OpenClaw's (--announce); this skill names no channel.
Inspect: openclaw cron list. Remove: openclaw cron rm --name hkex-li-daily-factor-monitor.
Notes & guarantees
One writable home (~/.config/hkex-li-daily-factor-monitor, override
HKEX_LI_MONITOR_HOME); nothing is read/written in the skill folder.
Copyright-safe: PDFs live only in the scratch dir for the current run and are
deleted in Step 6 and by the EXIT trap. Only the extracted factor digest leaves the run.
Portable / no hard-coding: every URL, endpoint, keyword, category gate, and
path is in the config block; swap them there, not in the steps.
Minimal Python: discovery and filtering are pure curl+jq; Python is a PDF
fallback only (scripts/pdf_to_text.py), used when pdftotext is unavailable.
