Skill Change Logging

Skill Change Logging

Use this skill whenever a skill file changes — both the 3rd-party game-dev skills under frb-skills/ and the 1st-party engine-contributor skills under .claude/skills/. Log the canonical path (e.g. frb-skills/animation/SKILL.md, not the symlinked path).

Required Log File

• Path: .claude/skill_change_log.jsonl
• Format: one JSON object per line (JSONL)

When to Log

Always append one entry per changed skill when any of these occur:

• SKILL.md content edits
• frontmatter name or description updates
• new skill creation
• skill deletion
• significant skill restructure (for example, moving sections into references)

Do not skip logging because a change is "small". If behavior, routing, or guardrails changed, log it.

Required Fields Per Entry

Each JSON object must include:

• id: integer UTC epoch milliseconds at write time (append-only friendly)
• timestamp_utc: ISO-8601 UTC timestamp at millisecond precision (YYYY-MM-DDTHH:mm:ss.fffZ)
• skill: skill name (folder name or frontmatter name)
• skill_file: repo-relative path
• change_type: create, update, delete, or restructure
• lines_added: integer from git diff --numstat
• lines_removed: integer from git diff --numstat
• line_ranges_added: array of 1-based line ranges in the post-change file (e.g. ["42-57","89-89"])
• line_ranges_removed: array of 1-based line ranges in the pre-change file (e.g. ["40-52"])
• motivating_sample_project: sample project path that motivated the change, or "none" if not sample-driven
• reason: concise but complete need statement

Logging Workflow

1. Make skill edits.
2. Run git diff --numstat -- <skill-file-paths>.
3. Run git diff -U0 -- <skill-file-paths> and capture hunk line ranges.
4. Set id to current UTC epoch milliseconds.
5. Append one JSON line per changed skill to .claude/skill_change_log.jsonl.
6. Keep reasons short, specific, and action-oriented.

ID Rules

• IDs are global across the file (not per skill).
• IDs must be unique; they do not need to be contiguous.
• Use UTC epoch milliseconds to avoid reading the existing log for max-id lookup.
• If two entries are created in the same millisecond, increment by +1 locally for subsequent entries in that write batch.

Line Range Rules

• Use 1-based line numbers.
• Use start-end strings; for single lines use N-N.
• line_ranges_added refers to post-change file line positions (+ hunks).
• line_ranges_removed refers to pre-change file line positions (- hunks).

Timestamp Rule

• Use UTC only and include trailing Z.
• Normalize to millisecond precision for consistency (for example, 2026-04-22T06:30:00.123Z).

Reason Writing Rules

• State the observed friction or risk.
• State why the new instruction prevents repeat failure.
• Avoid paragraphs; 1-2 sentences max.

Example Entry

{"id":1776840000123,"timestamp_utc":"2026-04-21T00:00:00.123Z","skill":"orchestrator","skill_file":".claude/skills/orchestrator/SKILL.md","change_type":"update","lines_added":8,"lines_removed":2,"line_ranges_added":["117-124"],"line_ranges_removed":["117-118"],"motivating_sample_project":"samples/auto/AutoEvalSimCopterSample","reason":"Full sample build can fail due unrelated engine errors; added fallback guidance to validate generated sample with isolated build and explicit blocker attribution."}