From example-skills
Rescues substantive inline content from conversation transcripts and promotes it to durable plan files with frontmatter, chezmoi-source propagation, and series registration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/example-skills:transcript-promotionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Lift substantive inline content from the ephemeral transcript surface to the durable plan-file surface. Extract verbatim, prepend canonical frontmatter, propagate to chezmoi-source so the autoCommit+autoPush cascade fires, and register the artifact in any series it belongs to.
Lift substantive inline content from the ephemeral transcript surface to the durable plan-file surface. Extract verbatim, prepend canonical frontmatter, propagate to chezmoi-source so the autoCommit+autoPush cascade fires, and register the artifact in any series it belongs to.
Sessions produce two kinds of substantive output:
Write|Edit tool hooks and naturally land on disk + remote.Class (2) is durable in the JSONL transcript but invisible to ~/.claude/plans/INDEX.md, MEMORY.md, and the chezmoi-source mirror. The transcript is on disk, but the content is buried inside conversation text rather than promoted to a discoverable artifact. A future session reading the plans index sees nothing; the content effectively dies with context exit.
Genesis case (2026-05-20 session 9cb55c4d): three engine reference docs (LOG #1 statusLine, LOG #2 Hooks, LOG #3 Subagents) delivered inline. LOG #1 was persisted to a plan file by the same session. LOG #2 and #3 were marked "inline only — not file-persisted" in the closeout. Two days later (2026-05-22), under explicit prompt to verify durability, they were extracted from the JSONL and promoted via the protocol now codified in this skill.
Pairs with artifact-resurfacing as the inverse motion:
artifact-resurfacing — citation points at nothing → reconcile the citationtranscript-promotion — content exists with no citation → mint the citationBoth clear different sides of the same drift entropy.
This skill is propagate-with-explicit-cascade for routine plan files, propose-not-apply for any constitutional surface.
~/.claude/plans/ may be written directly; the chezmoi auto-sync hook fails for bash-redirect file creation, so the skill manually runs chezmoi add to bring source into sync and let autoCommit+autoPush fire. This is the documented chezmoi gotcha protocol from home-scope CLAUDE.md.CLAUDE.md, MEMORY.md, governance-rules.json, registry-v2.json, any seed.yaml, INST-INDEX-RERUM-FACIENDARUM.md — never written by this skill. If transcript content names changes to a constitutional surface, defer to the conductor.main branch requires explicit per-session push authorization. This skill commits but surfaces the push decision to the user when the target is a public-main branch.Discovery → propose-frontmatter → propagate via chezmoi → register in series. Four phases, last two require user-derived authorization for non-routine targets.
~/.claude/plans/..."JSONL ✓ / plan file ✗qa-audit of substantive deliverables finds class-(2) content with no on-disk citationThe JSONL transcript is the canonical source. Extract assistant text and locate the content boundary by section anchor (preferred) or line range (fallback).
bash scripts/extract-anchor-range.sh \
--jsonl ~/.claude/projects/<scope>/<project-uuid>.jsonl \
--start-anchor "^## LOG #2 — Hooks: Complete Reference" \
--end-anchor "^## LOG #3 — Subagents: Complete Reference" \
--output "$CLAUDE_JOB_DIR/extracted-log-2.md"
The script:
assistant-type entries, concatenates .message.content[].text via jq.$CLAUDE_JOB_DIR (background-session safe path).Verbatim is non-negotiable. The transcript is the canonical version; re-authoring breaks the audit trail. Future drift-reconciliation by artifact-resurfacing should be able to grep the transcript for the same string and find it.
Prepend the standard frontmatter block. Required fields:
---
title: <Subject> — <Reference-Type>
date: <YYYY-MM-DD of original delivery, not promotion date>
scope: home (~/.claude/plans/) | repo (<path>) | organ (<organ>)
status: reference
extracted_from: <jsonl-path>
extraction_date: <YYYY-MM-DD of promotion>
related:
- <sibling-artifact-paths>
- <upstream-doc-urls>
- <series-siblings if part of a series>
---
# <Title>
## Why this file exists
<One-paragraph rationale: who delivered it, when, why it's being promoted now, what precedent it mirrors.>
---
<verbatim extracted content>
For series content (LOG #N), the related: block includes all siblings in the series, allowing later members to grep-discover earlier ones via the cross-link.
python3 scripts/propose-frontmatter.py \
--title "Claude Code Hooks — Complete Options Reference" \
--date 2026-05-20 \
--scope home \
--extracted-from ~/.claude/projects/-Users-4jp/9cb55c4d-3191-4b61-a8e8-192e4710affb.jsonl \
--series engine-log \
--series-index 2 \
--body "$CLAUDE_JOB_DIR/extracted-log-2.md" \
--output ~/.claude/plans/2026-05-20-hooks-options-reference.md
The script enforces the schema, prepends frontmatter, prints the resulting file path. Slug convention: YYYY-MM-DD-<topic-slug>-options-reference.md for engine-log series; YYYY-MM-DD-<topic-slug>.md for one-offs.
Bash-redirect / cat > file creation bypasses the PostToolUse Write|Edit hook that fires domus-memory-sync. The runtime file exists but never reaches chezmoi-source or remote. This is a documented silent-failure class — see references/known-promotion-pitfalls.md.
Manual recovery is the chezmoi-documented protocol:
bash scripts/propagate-via-chezmoi.sh ~/.claude/plans/2026-05-20-hooks-options-reference.md ~/.claude/plans/2026-05-20-subagents-options-reference.md
The script:
chezmoi add <runtime-paths> to copy runtime → source.git push needed for the chezmoi-source repo).git -C <chezmoi-source> log @{u}..HEAD --oneline should be empty.For non-chezmoi-managed plan files (per-repo .claude/plans/), the script falls back to git add + manual-commit-and-push surfacing.
A solitary promoted artifact is durable. A series member needs registration so future members can discover the canonical series register.
For the engine-log series (LOG #N pattern), update references/engine-log-series.md in this skill with the new entry:
| N | YYYY-MM-DD | Topic | Slug | Genesis session |
|---|---|---|---|---|
| 1 | 2026-05-20 | statusLine | 2026-05-20-statusline-options-reference | 9cb55c4d |
| 2 | 2026-05-20 | Hooks | 2026-05-20-hooks-options-reference | 9cb55c4d (extracted 2026-05-22 in beeff468) |
| 3 | 2026-05-20 | Subagents | 2026-05-20-subagents-options-reference | 9cb55c4d (extracted 2026-05-22 in beeff468) |
| ... | ... | ... | ... | ... |
For ad-hoc one-off promotions (not part of a series), no register update needed — the artifact's frontmatter related: cross-links suffice.
If promotion exposes a new silent-failure class (e.g., a new way auto-sync gets bypassed), append a row to references/known-promotion-pitfalls.md and surface an IRF row proposal. The skill's prevention surface grows monotonically.
CLAUDE.md, MEMORY.md, governance-rules.json, registry-v2.json, any seed.yaml, or INST-INDEX-RERUM-FACIENDARUM.md directly. IRF row proposals surface to the user.<system-reminder> blocks or <command-message> blocks (those are infrastructure, not deliverable content).main without explicit per-session push authorization.scripts/extract-anchor-range.sh — anchor-bounded transcript extractor; verifies anchors exist (Rule #12) before slicing.scripts/propose-frontmatter.py — frontmatter generator with schema validation and series-aware related: linking.scripts/propagate-via-chezmoi.sh — chezmoi-add wrapper with parity verification; surfaces non-chezmoi targets for manual push.references/engine-log-series.md — register of the LOG #N series; living document, append-only.references/known-promotion-pitfalls.md — silent-failure classes encountered during promotion; append-only.references/composition-with-closeout.md — how this skill chains with /closeout (closeout flags candidates; this skill executes the promotion).references/composition-with-artifact-resurfacing.md — the inverse-motion pair; when to invoke which.examples/2026-05-20-engine-logs-2-and-3.md — the genesis case: LOG #2 (Hooks) and LOG #3 (Subagents) extracted from JSONL 9cb55c4d and promoted to plan files in session beeff468 (2026-05-22). Full protocol trace including the silent-failure discovery for bash-redirect bypass of auto-sync.<system-reminder> infrastructure as if it were substantive contentextracted_from: field when the transcript has rotated out (if the JSONL is gone, the canonical source is gone; surface this rather than backfill)~/.claude/plans/YYYY-MM-DD-{slug}.md discipline.| Skill | Role | When |
|---|---|---|
closeout | discovers candidates | end of session; flags "inline only" deliverables |
transcript-promotion (this) | executes the promotion | when user invokes or when closeout candidates need durability |
artifact-resurfacing | inverse motion | when promoted content's citation later goes stale and needs reconciliation |
cross-agent-handoff | carries the register | promotion register travels in the handoff to the next session |
qa-audit | verifies promotion success | after promotion, audits whether all candidates actually landed on disk + remote |
consolidate-memory | indexes new artifacts | promoted plan files referenced from memory via [[name]] links get curated here |
The skill is designed to grow monotonically without ever overwriting itself:
references/engine-log-series.md) — append-only; LOG #N grows to N+1, N+2, ad infinitum.references/known-promotion-pitfalls.md) — append-only; each new silent-failure class discovered during promotion gets a row.The skill ages well because every new use case enriches the prevention surface. Drift is detected, codified, and surfaced — not papered over.
npx claudepluginhub a-organvm/a-i--skills --plugin document-skillsProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.