Diag Log Skill | Agent Skills

Diag Log

Overview

Provide a reusable logger script for recording skill or MCP error/conflict/warning/info events to ~/.codex/diag-events.ndjson with concurrency-safe appends.

Quick Start

Call the logger in any skill or MCP wrapper when an error, conflict, warning, or informational event occurs.

~/.codex/skills/diag-log/scripts/log_diag_event.sh \
  --event-type "error" \
  --source "skill" \
  --name "frontend-design" \
  --message "command failed" \
  --meta '{"exitCode":1}'

Logger Script

Path: ~/.codex/skills/diag-log/scripts/log_diag_event.sh
Required args:
- --event-type <error|conflict|warning|info>
Required when --event-type conflict:
- --conflict-type <lock_timeout|lock_contention|resource_busy|concurrent_run>
Optional args:
- --source <skill|mcp|system|other>
- --name <skill_or_mcp_name>
- --message <string>
- --meta <json_string> (must be valid JSON)
- --lock-timeout <seconds> (default: 10)

Output Format (NDJSON)

Each call appends one line with at least:

{ "ts": "<ISO8601>", "event_type": "error|conflict|warning|info" }

When provided, conflict_type, source, name, message, and meta are included.

Concurrency Behavior

Prefer flock when available.
If flock is not available, use an O_EXCL lockfile fallback.
If lock acquisition exceeds --lock-timeout, append a conflict event with:
- event_type: "conflict"
- conflict_type: "lock_timeout"
- message: "lock timeout after <seconds>s"
- then exit non-zero.

Examples

Conflict: lock contention

~/.codex/skills/diag-log/scripts/log_diag_event.sh \
  --event-type "conflict" \
  --conflict-type "lock_contention" \
  --source "mcp" \
  --name "figma" \
  --message "lock busy; retrying" \
  --meta '{"retry":2}'

Warning: fallback path

~/.codex/skills/diag-log/scripts/log_diag_event.sh \
  --event-type "warning" \
  --source "skill" \
  --name "context7-latest-usage" \
  --message "fallback to cached docs" \
  --meta '{"cacheAgeDays":3}'

Resources

scripts/

log_diag_event.sh: NDJSON logger with concurrency-safe appends and lock timeout handling.

Agent Skills: Diag Log

Install this agent skill to your local

Skill Files