shared-knowledge-artifact
Use a private Artifact page as an optional rendered and editing surface for an append-only knowledge ledger. Multiple agents (and the user) can read the lessons before starting work and append corrections afterwards. The Artifact is not universally authoritative: when a repository contains a Git-backed ledger, that repository ledger is the canonical record; the Artifact mirrors it and provides a convenient view or edit surface. Without a Git ledger, the published Artifact state is the durable record for that Artifact.
Trigger phrases
- create a shared artifact my other agents can learn from
- shared knowledge base / lessons-learned log / gotcha ledger for agents
- cross-agent memory page
- somewhere agents can record what they learned so they don't repeat it
Before writing any code
- Invoke the
artifact-capabilities skill, mandatory before declaring capabilities or writing any window.claude.* code.
- Invoke the
artifact-design skill, which calibrates the design treatment.
- Resolve the durable store by invoking the
context-repo skill. That store holds the Git-backed ledger. If it comes back BLOCKED, or the user declines when that skill asks, publish the artifact anyway and skip the Git ledger, labelled NOT_MIRRORED: <reason> in the deliverable. The store must never block publishing.
- Read the user's actual rules (
CLAUDE.md, any verification/preferences doc, agent memory), and read the current Git ledger directly when one exists (ledger.json at the root of a resolved store, or a repository ledger already in the checkout). Seed the ledger with real lessons already recorded there, 6-10 when that many exist, or all available real lessons if fewer than six are found. Skip any lesson already present in the store's ledger.json so a new page does not reseed what is already recorded there. No lorem, no invented examples: a ledger that opens with fake entries never gets used.
Authority and reconciliation
- If a Git-backed ledger exists, it is authoritative over the Artifact. Codex and other non-Claude agents must read and update that repository ledger directly; they must not require Artifact access.
- Before writing either surface, read the current repository ledger and the current Artifact state when both exist. Do not write from a stale page or cached copy.
- Notes added in the Artifact must be appended back to the Git ledger, using the repository's schema and append-only rules, before they are treated as shared guidance. Record the resulting note ID or the reason it was not written.
- If the Artifact and Git ledger disagree, preserve both histories but resolve the usable guidance in favor of Git. Refresh or reconcile the Artifact from Git rather than overwriting the repository record.
- If no Git ledger exists, the Artifact's published
#ledger-state is authoritative for that Artifact. Do not imply that it is shared with non-Claude agents unless it has been exported to a repository ledger.
Persistence mechanism
- Declare
capabilities: {artifact: {}} at publish time.
- Store the Artifact surface's data as a JSON object inside
<script type="application/json" id="ledger-state">. That block is authoritative for the published Artifact version; the visible page is rendered from it at load. When a Git ledger exists, this page state remains a mirror and Git remains authoritative overall. Never serialize the live DOM to save.
- To persist: snapshot
document.documentElement.outerHTML once at script start (pristine source, before any rendering), then on save splice the new JSON into that snapshot's #ledger-state block, prepend <!doctype html>, and call artifact.publish(doc).
- Get the namespace with
const artifact = await claude.use("artifact"); branch on null (this view cannot write) and render a read-only state instead of a broken control.
- Handle publish errors by code:
conflict means someone published first and every view reloads to the winner: no retry, tell the person to re-add; not_granted / not_writer means read-only.
- Publish only after an explicit user action, never on load; batch rapid edits into one publish.
- Escape
</script when writing the JSON back, and escape every interpolated note field on render.
Write through to the context store
The store holds the Git-backed ledger, so per "Authority and reconciliation" it is the canonical record and the page is the view onto it. After a successful publish performed by this skill (not a viewer's later edit on the page), extract the #ledger-state JSON from the published document and append any note it holds that the store does not, to the notes array of the store's root ledger.json, with a fresh id in the store's own sequence. One shared ledger, not one per artifact: never add a knowledge/<slug>/ tree beside it. Message chore(knowledge): append <n> notes from <slug> where <n> is the number actually appended. Follow the context-repo caller contract in full: take the lease, git pull --rebase, run the store's validator, one commit, never force, never edit or remove an existing note.
If the store did not resolve (BLOCKED or declined in the "Before writing any code" step), skip this section entirely and report NOT_MIRRORED with the reason; do not retry the resolution mid-run.
Limitation, stated plainly: notes added on the page by a viewer are not written through, because no agent is present when that happens. Those notes reach the ledger only on the next agent-driven publish, and until then they are not shared guidance. Say so on the page rather than letting a viewer assume their note is already canonical.
Note schema
One fact per entry:
{"id":"n9","kind":"lesson|trap|pref","scope":"shell|review|github|...",
"title":"the rule in one line",
"body":"the concrete behaviour, specific enough to act on",
"why":"the failure that made this a rule",
"author":"model or agent name","date":"YYYY-MM-DD"}
Kinds: lesson = a habit that holds; trap = something that silently produces a wrong answer; pref = how the user wants the work done.
UI the page must have
- Header: name, one paragraph on what the ledger is for, and live counts (total, traps, lessons, preferences) in
tabular-nums.
- Note list, newest first: kind tag, scope tag, author, date, title, body, and a
Why: line. Kind tags use semantic colour (trap = critical, pref = warning, lesson = accent), separate from the page accent.
- Scope filter chips derived from the data, including an
all chip, with aria-pressed state.
- An "Add a note" form (kind, scope, author, title, body, why) that appends to the JSON and publishes, with an inline status line reporting published / conflict / read-only.
- A "Protocol for agents" section on the page itself: when a Git ledger exists, read that repository ledger directly before substantive work; Codex and other non-Claude agents must use it directly. Claude agents may read the Artifact with the Artifact tool
action: "read" as a rendered surface, then parse the #ledger-state JSON rather than scraping the DOM. In either case, append, don't rewrite, re-read before writing because another agent may have updated the source, and include the failure that caused each note. Include the schema snippet and the Git reconciliation rule.
- Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's
CLAUDE.md already says it, or a review bot already catches it, leave it out: a littered ledger is worse than a thin one.
Design constraints
- Utilitarian but genuinely polished: this is a reference document, not a landing page. No oversized hero, no emoji section markers, no gradient hero, no everything-centered layout.
- Avoid the AI-default looks: warm cream + serif + terracotta, near-black + acid green, Inter or Space Grotesk as the "safe" face.
- Pair a display face, a body face, and a mono utility face from Google Fonts (the only permitted external host), each with a real fallback stack.
- Theme-aware in all three states: full light palette as tokens on bare
:root; redefined under @media (prefers-color-scheme: dark) guarded as :root:not([data-theme="light"]); redefined again under :root[data-theme="dark"]. Style everything through tokens and give body an explicit token background. No colour whose only definition sits inside a media or [data-theme] block.
- Layout with flex/grid +
gap, not per-element margins. Wide content in its own overflow-x: auto container. Visible focus states. Respect prefers-reduced-motion.
- Title: a short, specific noun-phrase product name (2-4 words), no dash-explainer. Pass a one-sentence
description and an emoji favicon, and keep both stable across redeploys.
Deliverable
When an Artifact surface is requested, write the HTML to a file and publish it with the Artifact tool, then report:
- the URL;
- that it stays private until shared from the page's share menu;
- the exact instructions another agent needs: read via Artifact
action: "read" with that URL, and write by appending to notes and republishing with url set to that URL (a publish without url forks a separate artifact instead of updating this one);
- when a Git ledger exists, the repository path and the reconciliation result, making clear that other agents should read and write Git directly and that Git wins any disagreement, plus the note ids appended and the commit SHA in the context store (
ledger.json at <sha>), or NOT_MIRRORED: <reason> if the store did not resolve.
Notes
- The full copy-paste prompt version of this workflow lives in
references/prompt.txt: hand it to another agent or session verbatim.
- Redeploy by republishing the same file path in the same conversation, or by passing
url from any other conversation.
1---2name: shared-knowledge-artifact3description: shared-knowledge-artifact4---56# shared-knowledge-artifact78Use a private Artifact page as an optional rendered and editing surface for an append-only knowledge ledger. Multiple agents (and the user) can read the lessons before starting work and append corrections afterwards. The Artifact is not universally authoritative: when a repository contains a Git-backed ledger, that repository ledger is the canonical record; the Artifact mirrors it and provides a convenient view or edit surface. Without a Git ledger, the published Artifact state is the durable record for that Artifact.910## Trigger phrases1112- create a shared artifact my other agents can learn from13- shared knowledge base / lessons-learned log / gotcha ledger for agents14- cross-agent memory page15- somewhere agents can record what they learned so they don't repeat it1617## Before writing any code18191. Invoke the `artifact-capabilities` skill, mandatory before declaring `capabilities` or writing any `window.claude.*` code.202. Invoke the `artifact-design` skill, which calibrates the design treatment.213. Resolve the durable store by invoking the `context-repo` skill. That store holds the Git-backed ledger. If it comes back BLOCKED, or the user declines when that skill asks, publish the artifact anyway and skip the Git ledger, labelled `NOT_MIRRORED: <reason>` in the deliverable. The store must never block publishing.224. Read the user's actual rules (`CLAUDE.md`, any verification/preferences doc, agent memory), and read the current Git ledger directly when one exists (`ledger.json` at the root of a resolved store, or a repository ledger already in the checkout). **Seed the ledger with real lessons already recorded there, 6-10 when that many exist, or all available real lessons if fewer than six are found**. Skip any lesson already present in the store's `ledger.json` so a new page does not reseed what is already recorded there. No lorem, no invented examples: a ledger that opens with fake entries never gets used.2324## Authority and reconciliation2526- If a Git-backed ledger exists, it is authoritative over the Artifact. Codex and other non-Claude agents must read and update that repository ledger directly; they must not require Artifact access.27- Before writing either surface, read the current repository ledger and the current Artifact state when both exist. Do not write from a stale page or cached copy.28- Notes added in the Artifact must be appended back to the Git ledger, using the repository's schema and append-only rules, before they are treated as shared guidance. Record the resulting note ID or the reason it was not written.29- If the Artifact and Git ledger disagree, preserve both histories but resolve the usable guidance in favor of Git. Refresh or reconcile the Artifact from Git rather than overwriting the repository record.30- If no Git ledger exists, the Artifact's published `#ledger-state` is authoritative for that Artifact. Do not imply that it is shared with non-Claude agents unless it has been exported to a repository ledger.3132## Persistence mechanism3334- Declare `capabilities: {artifact: {}}` at publish time.35- Store the Artifact surface's data as a JSON object inside `<script type="application/json" id="ledger-state">`. That block is authoritative for the published Artifact version; the visible page is **rendered from it** at load. When a Git ledger exists, this page state remains a mirror and Git remains authoritative overall. Never serialize the live DOM to save.36- To persist: snapshot `document.documentElement.outerHTML` **once at script start** (pristine source, before any rendering), then on save splice the new JSON into that snapshot's `#ledger-state` block, prepend `<!doctype html>`, and call `artifact.publish(doc)`.37- Get the namespace with `const artifact = await claude.use("artifact")`; branch on `null` (this view cannot write) and render a read-only state instead of a broken control.38- Handle publish errors by code: `conflict` means someone published first and every view reloads to the winner: no retry, tell the person to re-add; `not_granted` / `not_writer` means read-only.39- Publish only after an explicit user action, never on load; batch rapid edits into one publish.40- Escape `</script` when writing the JSON back, and escape every interpolated note field on render.4142## Write through to the context store4344The store holds the Git-backed ledger, so per "Authority and reconciliation" it is the canonical record and the page is the view onto it. After a successful publish performed by this skill (not a viewer's later edit on the page), extract the `#ledger-state` JSON from the published document and append any note it holds that the store does not, to the `notes` array of the store's root `ledger.json`, with a fresh id in the store's own sequence. One shared ledger, not one per artifact: never add a `knowledge/<slug>/` tree beside it. Message `chore(knowledge): append <n> notes from <slug>` where `<n>` is the number actually appended. Follow the `context-repo` caller contract in full: take the lease, `git pull --rebase`, run the store's validator, one commit, never force, never edit or remove an existing note.4546If the store did not resolve (BLOCKED or declined in the "Before writing any code" step), skip this section entirely and report `NOT_MIRRORED` with the reason; do not retry the resolution mid-run.4748Limitation, stated plainly: notes added on the page by a viewer are not written through, because no agent is present when that happens. Those notes reach the ledger only on the next agent-driven publish, and until then they are not shared guidance. Say so on the page rather than letting a viewer assume their note is already canonical.4950## Note schema5152One fact per entry:5354```json55{"id":"n9","kind":"lesson|trap|pref","scope":"shell|review|github|...",56 "title":"the rule in one line",57 "body":"the concrete behaviour, specific enough to act on",58 "why":"the failure that made this a rule",59 "author":"model or agent name","date":"YYYY-MM-DD"}60```6162Kinds: **lesson** = a habit that holds; **trap** = something that silently produces a *wrong* answer; **pref** = how the user wants the work done.6364## UI the page must have6566- Header: name, one paragraph on what the ledger is for, and live counts (total, traps, lessons, preferences) in `tabular-nums`.67- Note list, newest first: kind tag, scope tag, author, date, title, body, and a `Why:` line. Kind tags use semantic colour (trap = critical, pref = warning, lesson = accent), separate from the page accent.68- Scope filter chips derived from the data, including an `all` chip, with `aria-pressed` state.69- An "Add a note" form (kind, scope, author, title, body, why) that appends to the JSON and publishes, with an inline status line reporting published / conflict / read-only.70- A "Protocol for agents" section **on the page itself**: when a Git ledger exists, read that repository ledger directly before substantive work; Codex and other non-Claude agents must use it directly. Claude agents may read the Artifact with the Artifact tool `action: "read"` as a rendered surface, then parse the `#ledger-state` JSON rather than scraping the DOM. In either case, **append, don't rewrite**, re-read before writing because another agent may have updated the source, and include the failure that caused each note. Include the schema snippet and the Git reconciliation rule.71- Gatekeeping copy: only non-obvious, durable, cross-cutting lessons. If a repo's `CLAUDE.md` already says it, or a review bot already catches it, leave it out: a littered ledger is worse than a thin one.7273## Design constraints7475- Utilitarian but genuinely polished: this is a reference document, not a landing page. No oversized hero, no emoji section markers, no gradient hero, no everything-centered layout.76- Avoid the AI-default looks: warm cream + serif + terracotta, near-black + acid green, Inter or Space Grotesk as the "safe" face.77- Pair a display face, a body face, and a mono utility face from Google Fonts (the only permitted external host), each with a real fallback stack.78- Theme-aware in all three states: full light palette as tokens on bare `:root`; redefined under `@media (prefers-color-scheme: dark)` guarded as `:root:not([data-theme="light"])`; redefined again under `:root[data-theme="dark"]`. Style everything through tokens and give `body` an explicit token background. No colour whose only definition sits inside a media or `[data-theme]` block.79- Layout with flex/grid + `gap`, not per-element margins. Wide content in its own `overflow-x: auto` container. Visible focus states. Respect `prefers-reduced-motion`.80- Title: a short, specific noun-phrase product name (2-4 words), no dash-explainer. Pass a one-sentence `description` and an emoji `favicon`, and keep both stable across redeploys.8182## Deliverable8384When an Artifact surface is requested, write the HTML to a file and publish it with the Artifact tool, then report:8586- the URL;87- that it stays private until shared from the page's share menu;88- the exact instructions another agent needs: read via Artifact `action: "read"` with that URL, and write by appending to `notes` and republishing **with `url` set to that URL** (a publish *without* `url` forks a separate artifact instead of updating this one);89- when a Git ledger exists, the repository path and the reconciliation result, making clear that other agents should read and write Git directly and that Git wins any disagreement, plus the note ids appended and the commit SHA in the context store (`ledger.json` at `<sha>`), or `NOT_MIRRORED: <reason>` if the store did not resolve.9091## Notes9293- The full copy-paste prompt version of this workflow lives in `references/prompt.txt`: hand it to another agent or session verbatim.94- Redeploy by republishing the same file path in the same conversation, or by passing `url` from any other conversation.
oleg-koval