X-Financial/hermes/skills/domain/x-financial-callback/SKILL.md

name, description

name	description
x-financial-callback	Use when a Hermes task for X-Financial must report progress or completion back to the backend through the single generic callback endpoint.

X-Financial Callback

Use this skill for every X-Financial task that must notify the backend after Hermes finishes work.

Callback contract

Send exactly one HTTP POST request to the callback URL provided in the task payload.

Use:

• Header: Authorization: Bearer <callback_token>
• Header: Content-Type: application/json
• Body:

{
  "type": "task_type_from_input",
  "run_id": "agent_run_id_from_input",
  "status": "succeeded",
  "summary": "short human-readable summary",
  "payload": {}
}

Rules

• Always preserve the incoming type and run_id.
• Execute the callback directly for server-dispatched tasks; do not ask the user for a second confirmation.
• Use scripts/send_callback.py for the actual HTTP request so large JSON bodies, quotes, and multilingual text are encoded safely.
• For normal tasks, prefer letting the script build the generic envelope for you via --type, --run-id, --status, and --summary; then the JSON file on stdin should contain only the task-specific business payload.
• Prefer sending a validated JSON file for non-trivial payloads: python3 ~/.hermes/skills/domain/x-financial-callback/scripts/send_callback.py --url "$CALLBACK_URL" --token "$CALLBACK_TOKEN" < /tmp/x-financial-callback.json
• Before sending a large payload, validate it with python3 -m json.tool /tmp/x-financial-callback.json >/dev/null.
• For large multilingual payloads, write /tmp/x-financial-callback.json with the write_file tool first. Do not generate helper Python source files or shell heredocs merely to build JSON.
• Use status: "running" only for optional progress updates.
• Use status: "succeeded" once when the task is complete.
• Use status: "failed" once when the task cannot be completed, and include an error string.
• Put task-specific business data only inside payload.
• Do not invent extra callback endpoints. X-Financial accepts Hermes callbacks through one shared endpoint only.
• If the callback fails, retry the same request up to 3 times before returning failure.

Preferred command

python3 ~/.hermes/skills/domain/x-financial-callback/scripts/send_callback.py \
  --url "$CALLBACK_URL" \
  --token "$CALLBACK_TOKEN" \
  --type "$TASK_TYPE" \
  --run-id "$RUN_ID" \
  --status succeeded \
  --summary "short human-readable summary" \
  < /tmp/x-financial-callback.json