How do I install the Evidence Recorder skill?

Run npx skillmds@latest add kmshihab7878/evidence-recorder in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Evidence Recorder safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Evidence Recorder?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Evidence Recorder free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Evidence Recorder?

kmshihab7878 (@kmshihab7878) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Evidence Recorder by kmshihab7878 — Agent Skill

Name: Evidence Recorder
Author: kmshihab7878

Evidence Recorder

Append one JSONL record to ~/.claude/evolution/records/ when a correction, a non-obvious win, or a repeated rework pattern occurs. Use sparingly — only when the event is load-bearing for future behavior. Do not log routine tool calls; the PreToolUse usage-logger already does that.

kmshihab7878 Updated Sep 17, 2026

File contents

evidence-recorder

When to auto-use

Record an event when any of these are true:

The user explicitly corrects an approach ("no, do X instead", "stop doing Y", "actually we prefer Z").
A non-obvious technique produced a clear win (it worked when a naive approach would have failed).
You notice a repeated rework pattern in the same session (doing X, being told to redo as Y, 2+ times).
An adaptation was proposed or applied.

When NOT to use

Routine file edits, tool calls, or test runs — those are already captured by the PreToolUse usage-logger.
Ambiguous events. If you're not sure it's a pattern, it's noise.
To journal your reasoning — this is an evidence store, not a diary.

How to record

Append one JSON line to the correct file:

TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
SESSION="${CLAUDE_SESSION_ID:-unknown}"   # populate from SessionStart hook if available
PROJECT=$(basename "$(pwd)")

python3 -c "
import json
rec = {
  'ts': '$TS',
  'session': '$SESSION',
  'project': '$PROJECT',
  'type': 'correction',              # one of: correction | win | friction | adaptation
  'scope': 'global',                 # global | project-specific | language:<x> | stack:<x>
  'summary': 'User corrected: prefer rsync --delete over rm before copy for setup sync.',
  'context': 'During sync of ~/.claude from repo; this prevented orphan files.',
  'id': 'evid-$TS-correction'
}
with open('$HOME/.claude/evolution/records/corrections.jsonl','a') as f:
  f.write(json.dumps(rec)+'\n')
"

Type → file mapping:

correction → records/corrections.jsonl
win → records/outcomes.jsonl
friction → records/outcomes.jsonl (with success: false)
adaptation → records/adaptations.jsonl

Schema (all fields required unless marked optional)

ts — ISO-8601 UTC
session — session id if available
project — basename of CWD
type — correction / win / friction / adaptation
scope — global / project-specific / language: / stack:
summary — one sentence, ≤ 200 chars
context — optional short context, ≤ 500 chars
id — unique identifier

Quality bar

A good record is terse, falsifiable, and future-useful. Bad example: "user was frustrated." Good example: "user prefers rsync --delete for setup sync (prevents orphan files)."

---name: evidence-recorderdescription: Append one JSONL record to ~/.claude/evolution/records/ when a correction, a non-obvious win, or a repeated rework pattern occurs. Use sparingly — only when the event is load-bearing for future behavior. Do not log routine tool calls; the PreToolUse usage-logger already does that.---# evidence-recorder## When to auto-useRecord an event when **any** of these are true:- The user explicitly corrects an approach ("no, do X instead", "stop doing Y", "actually we prefer Z").- A non-obvious technique produced a clear win (it worked when a naive approach would have failed).- You notice a repeated rework pattern in the same session (doing X, being told to redo as Y, 2+ times).- An adaptation was proposed or applied.## When NOT to use- Routine file edits, tool calls, or test runs — those are already captured by the PreToolUse usage-logger.- Ambiguous events. If you're not sure it's a pattern, it's noise.- To journal your reasoning — this is an evidence store, not a diary.## How to recordAppend one JSON line to the correct file:```bashTS=$(date -u +%Y-%m-%dT%H:%M:%SZ)SESSION="${CLAUDE_SESSION_ID:-unknown}" # populate from SessionStart hook if availablePROJECT=$(basename "$(pwd)")python3 -c "import jsonrec = { 'ts': '$TS', 'session': '$SESSION', 'project': '$PROJECT', 'type': 'correction', # one of: correction | win | friction | adaptation 'scope': 'global', # global | project-specific | language:<x> | stack:<x> 'summary': 'User corrected: prefer rsync --delete over rm before copy for setup sync.', 'context': 'During sync of ~/.claude from repo; this prevented orphan files.', 'id': 'evid-$TS-correction'}with open('$HOME/.claude/evolution/records/corrections.jsonl','a') as f: f.write(json.dumps(rec)+'\n')"```Type → file mapping:- `correction` → `records/corrections.jsonl`- `win` → `records/outcomes.jsonl`- `friction` → `records/outcomes.jsonl` (with `success: false`)- `adaptation` → `records/adaptations.jsonl`## Schema (all fields required unless marked optional)- `ts` — ISO-8601 UTC- `session` — session id if available- `project` — basename of CWD- `type` — correction / win / friction / adaptation- `scope` — global / project-specific / language:<x> / stack:<x>- `summary` — one sentence, ≤ 200 chars- `context` — optional short context, ≤ 500 chars- `id` — unique identifier## Quality barA good record is terse, falsifiable, and future-useful. Bad example: "user was frustrated." Good example: "user prefers rsync --delete for setup sync (prevents orphan files)."

Frequently asked questions