skill-log: Protocol for skill logging

Any skill can log structured events into its own directory under .moollm/skills/<skill-name>/logs/. Filenames are time-big-endian so directory sort is chronological. One file per entry; body is YAML.

---

Contract

• Log directory: .moollm/skills/<skill_name>/logs/
  • <skill_name> = skill id (e.g. cursor-mirror, skill-snitch, skill-test). Use the same name as in skills/<name>/.
  • Resolve .moollm from env MOOLLM_ROOT or by walking up from cwd until a directory named .moollm exists. If not found, use cwd and create .moollm/skills/<skill_name>/logs/ there.
• Filename: YYYYMMDD-HHMMSS-<description_slug>.yml
  • Time: local, big-endian (year, month, day, hour, minute, second). Sortable.
  • <description_slug>: short, filesystem-safe (lowercase, hyphens for spaces/special; e.g. run-started, snitch-scan-done). Collision in same second: add suffix (e.g. run-started-1) or rely on slug variety.
• Body (YAML): At least timestamp (ISO or same as filename) and description (human string). Rest is free-form payload or top-level keys. Comments allowed (YAML Jazz).

---

Body schema (minimal)

timestamp: "2026-02-17T14:30:00"   # ISO or YYYYMMDD-HHMMSS
description: "run started"          # human-readable
# optional: any key-value; nested OK
payload: {}
# or top-level keys: event, result, duration, ...

---

Usage

Python (script or from another skill)

From repo root or any dir under MOOLLM:

# Option A: run the script
# python skills/skill-log/scripts/skill_log.py <skill_name> <description_slug> [key=value ...]

# Option B: import and call (if skill_log is on path)
from skill_log import log_entry
log_entry("cursor-mirror", "export-done", {"format": "json", "count": 42})

CLI

# One entry; payload as key=value pairs (optional)
python skills/skill-log/scripts/skill_log.py cursor-mirror export-done format=json count=42

# Or set MOOLLM_ROOT and run from anywhere
MOOLLM_ROOT=/path/to/moollm python skills/skill-log/scripts/skill_log.py skill-snitch scan-done skill=cursor-mirror

From another skill

• skill-snitch: After SCAN or AUDIT, log to .moollm/skills/skill-snitch/logs/ with slug e.g. scan-done, audit-done; payload can include skill path, finding count.
• skill-test: After a test run, log to .moollm/skills/skill-test/logs/ with slug e.g. suite-done, test-failed; payload can include suite name, pass/fail, duration.
• cursor-mirror: Optional: log export or tail events to .moollm/skills/cursor-mirror/logs/.

All use the same convention so snitch/test/mirror can read each other’s logs or aggregate under .moollm/logs/ later if desired.

---

TAIL (read recent entries)

The script can support tail subcommand: list or cat recent files from a skill’s log dir (sort by filename = time order). Implement in same script or a separate one; protocol is “same dir, same filename format.”

---

Relation to session-log

• session-log — Audit trail for the session (LOG/VIEW/SEARCH); often one shared stream or file.
• skill-log — Per-skill, file-per-event, time-big-endian filenames. Skills opt in; no central stream. Use for skill-specific traces, test runs, snitch reports. session-log and skill-log can coexist; tools can aggregate both.

---

Future

• MCP / API: Expose LOG and TAIL as MCP tools or HTTP so non-Python callers can log.
• Aggregation: A viewer that reads .moollm/skills/*/logs/ and merges by time for a single timeline.
• Rotation: Optional max files per skill or age-based cleanup; keep protocol simple first.