| name | session-log |
| description | Logs a session report as an HTML page, tracks vault context, extracts decisions, and outputs a /rename command. Use for /session-log, 'journal this session', 'log this work', 'session report', 'summarize/log/record this session', 'save session', 'capture session', or 'document what we did'. |
Session Log
Overview
Session-log composes the HTML report and publishes it directly with the Artifact tool. The skill owns the whole flow: where the file lives in the vault, what number it gets, the frontmatter metadata contract, HTML composition and publishing, post-write vault tracking, decision extraction, project-folder hygiene, and the closing /rename hand-off.
Announce at start: "I'm logging this session."
Why this report is designed fresh per session
Sessions come in many shapes — convergence loops, feature builds, research dives, incidents, refactors, decisions. A single h2-emoji-list template forces every session into the same form regardless of fit, and the artifact reads as a process log rather than a substance log. Load the artifact-design skill before composing any page content — it calibrates the design investment and shape to the session's character: a feature build reads naturally as a PR writeup, an incident or convergence loop as a timeline, a status update as a progress summary, a plan or decision as a decision record, an exploration as a multi-approach walkthrough.
Gotchas
- Load the
artifact-design skill before writing page content. The Artifact tool needs this step first — it is not optional polish.
- The
Artifact tool wraps the file in a document skeleton at publish time. It adds <!doctype html>…<head>…</head><body> around whatever the file holds — write page content only (a <title>, a <style> block, and the body markup). Do not include <!DOCTYPE>, <html>, <head>, or <body> tags in the file itself.
- The
Artifact tool redeploys to the same URL only within the current run. Editing the session's HTML file in a later step of this same skill run and calling Artifact again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
- Vault paths sit outside
.claude/. Headless vault paths (e.g., $OBSIDIAN_VAULT_PATH) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
- Sessions describe current state by convention. The state_description_blocker hook does not scan .html, but the rule at
~/.claude/rules/no-historical-clutter.md applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
write_existing_file_blocker rejects Write on existing paths. Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.- Obsidian frontmatter index is HTML-blind. Obsidian's native YAML-frontmatter parser reads only
.md files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by type: session-report does not.
Backend Detection (run before Step 1)
Determine which storage backend is available for the write path. First success wins.
- Headless vault — Bash
ob --version to verify the obsidian-headless CLI is installed. Check OBSIDIAN_VAULT_PATH env var or ~/.claude/vault/ for a vault directory. When the CLI check succeeds AND at least one of those paths resolves to a vault directory, set backend = "headless".
- Local vault — fall back to
~/.claude/vault/. Create ~/.claude/vault/sessions via mkdir -p if missing. Set backend = "local".
session-log writes with Write/Edit and publishes with Artifact, so it uses headless or local filesystem paths only. /session-tidy Phase 0 reuses this headless → local order and adds an Obsidian MCP branch for vault maintenance.
Session-number detection: Bash ls the project's session folder, parse filenames matching [N]. *.html or [N]. *.md. Highest N + 1. New project → start at 1.
Output paths:
- headless:
$OBSIDIAN_VAULT_PATH/sessions/[Project]/[N]. [Title].html (falls back to ~/.claude/vault/ when the env var is unset)
- local:
~/.claude/vault/sessions/[Project]/[N]. [Title].html
Announce the backend: "Using headless vault at [path]." or "Using local vault at ~/.claude/vault/. Install obsidian-headless and set the OBSIDIAN_VAULT_PATH environment variable (PowerShell: $env:OBSIDIAN_VAULT_PATH = '<path>'; POSIX shells: export OBSIDIAN_VAULT_PATH=<path>) to enable sync."
Step 1: Compose Session Metadata
Review the conversation to identify the session's primary outcome and the small set of facts a cold reader needs.
Resolve the metadata used by the frontmatter and the vault path:
- Project name: infer from conversation context
- Session number: from backend detection above
- Session ID: the session ID of the agent authoring this log, read from the
CLAUDE_CODE_SESSION_ID environment variable (PowerShell: $env:CLAUDE_CODE_SESSION_ID). This UUID names the authoring agent's own transcript file (<session-id>.jsonl), so the saved report points back to the exact session that produced it. When the variable is unset, use the literal unknown.
- Date: today's date
- Title: a 2–5 word summary of the session's primary outcome. Examples: "Amazon Auth Migration", "Source Loading Fix", "PR 475 Convergence". Avoid generic titles like "Bug Fixes".
The frontmatter contract every session report carries (inside an HTML comment, as the first child of <body>) is the metadata block in templates/frontmatter.md.
Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. Initial values for Step 2's Write: substitute concrete values for every placeholder — for session_id, write the value read from CLAUDE_CODE_SESSION_ID in step 1 (or unknown when the variable is unset); for vault_context_retrieved, write the literal value false (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits vault_context_retrieved to true if any of the three vault MCP tools fired this session.
Step 2: Compose and Publish the HTML via the Artifact Tool
Load the artifact-design skill before writing any content. Design the artifact for this session's character — a feature build reads naturally as a PR writeup, an incident or convergence loop as a timeline, a status update as a progress summary, a plan or decision as a decision record, an exploration as a multi-approach walkthrough. The report must answer for a cold reader, from the section headers alone, three questions: what shipped, why it matters, what impact it had. Process narration (commit-by-commit walks, agent gotchas, retry counts) belongs at the end, not in the opening sections.
Required as the first content line: the frontmatter HTML comment from step 1.
Required somewhere in the content: a <title> element naming the session — it names the browser tab and the artifact gallery entry.
Required as the first content section (after the frontmatter comment): an opening "What this session shipped" paragraph + bullets — written so a reader with zero prior context understands the outcome. For continuation sessions (where the substantive work landed in a prior session), recap the parent session's outcome briefly so the report stands alone.
Required: self-contained, responsive, theme-aware HTML. Inline all CSS in a <style> block and all JS inline; embed any images as data URIs — the Artifact tool's content security policy blocks external CDN scripts, stylesheets, fonts, and network requests. Use relative units so the layout holds at any width, and support both light and dark via prefers-color-scheme (or :root[data-theme] overrides).
No document wrapper tags. The Artifact tool wraps the file content in a <!doctype html>…<head>…</head><body> skeleton at publish time — write the <title>, <style>, and body markup directly, with no <!DOCTYPE>, <html>, <head>, or <body> tags of your own.
Beyond those requirements, design the shape that fits the session — the artifact-design skill's guidance covers typography, palette, and layout choices.
Write the file via the Write tool to the vault path. Create the project directory via mkdir -p if it does not exist.
Publish the file by calling the Artifact tool with file_path set to the vault path just written, favicon set to the fixed session-log favicon 📓 — this favicon stays the same across every session-log report so the series reads as one consistent collection; never swap it per session — and description set to a one-sentence subtitle summarizing the session. Capture the returned URL: it is the canonical URL for this session report, and it stays the same across every later Artifact call on this same file_path within the current run (steps 3 and 5 redeploy to it rather than minting a new one).
If the Write fails, output the HTML content in the conversation so the user can copy it manually. Before emitting the HTML to chat, resolve the vault_context_retrieved placeholder to true or false based on the same vault-MCP-tool scan that Step 3 would have run, and include the matching vault-context <li> line (Retrieved or Not retrieved) so the emitted HTML is a valid copy-paste artifact with complete frontmatter. Skip Step 3 and continue at step 4.
Step 3: Vault Context Tracking
This step runs automatically after step 2.
Review the conversation history for any use of these vault MCP tools (look only at tool calls the session made before /session-log itself ran):
mcp__obsidian__search_notesmcp__obsidian__read_notemcp__obsidian__read_multiple_notes
Edit the vault HTML via two Edit calls:
- Set the frontmatter
vault_context_retrieved field to true when any of the three tools fired this session, false otherwise.
- Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh
<h2>Notes</h2> block (in templates/frontmatter.md) at the end of the content.
If the report already has a notes / references section, use Edit to insert one matching child element at the end of that section. The element shape mirrors whatever the section already uses: an extra <li> before the closing </ul> for a list, an extra <dt>Vault context</dt><dd>…</dd> pair before the closing </dl> for a description list, an extra <p><strong>Vault context:</strong> …</p> before the section's closing tag for a paragraph-based section. Pick the form that matches the surrounding markup.
After both Edits land, call the Artifact tool again with the same file_path and the same favicon used in step 2 to redeploy the updated content. This updates the URL captured in step 2 in place; no new URL is minted.
Step 4: Decision Extraction
Scan the conversation for decisions, gotchas, or architectural choices that were not already saved via /remember. For each one found, ask the user via AskUserQuestion:
"I noticed this decision: [summary]. Save it to the vault via /remember?"
Only invoke /remember for decisions the user confirms; /remember writes the decision as a vault note. If no unrecorded decisions are found, skip silently.
Step 5: Session Tidy (Project Scope)
Scope: the current project's session folder only.
-
List files in the project's vault session folder via Bash ls.
-
Audit each .html and .md session file using the audit rules in session-tidy Phase 1 (naming, frontmatter completeness, type, status coherence, orphaned next-steps, categorization). session-tidy SKILL.md is the single home for those rules.
-
Auto-fix minor HTML metadata issues via Edit (this step's write path is HTML-oriented):
- Missing frontmatter fields that can be inferred (e.g.,
blocked: false when status is completed; vault_context_retrieved: false when the field is absent)
type field set to a wrong value (correct to session-report)
When the Edit touches the session report created in this run, call Artifact again with the same file_path and favicon from step 2 to redeploy — the URL captured in step 2 stays unchanged. When the Edit touches an older HTML session report published in a prior run, call Artifact on that file_path with no url argument, since this skill keeps no record of that file's earlier URL — this publishes that report at a new URL. Surface a Session [N] republished at a new URL: <url> line so the user can update any prior shares.
-
Report issues that need user input:
- Files with wrong naming convention (propose new name)
- Stale statuses (propose update to
completed or ask)
- Contradictory status/blocked combos
If no issues are found, skip silently. Do not report "all clean."
-
Rollup check: if the project has 5+ sessions and no Summary.html or Summary.md, mention it:
"This project has [N] sessions and no summary. Run /session-tidy for a project rollup."
Step 6: Finalize
Copy a /rename command to the user's clipboard via PowerShell:
pwsh -NoProfile -Command "Set-Clipboard '/rename [Project] - [Primary Outcome]'"
Then tell the user:
"Copied /rename [Project] - [Primary Outcome] to your clipboard. Paste it to rename this session."
The primary outcome comes from the session title resolved in step 1.
Run-and-report checklist
Folder map
SKILL.md — this hub.templates/frontmatter.md — the report frontmatter contract and the Step 3 notes block.
