| name | agent-context-crystallizer |
| description | Preserve high-signal work context with local checkpoints and session crystals using the agent-crystallize CLI. Use before compaction, handoff, session end, cross-agent transfer, after major decisions/findings/failures, or when the user asks to checkpoint, crystallize, preserve context, save open loops, or create a resume handoff. |
Agent Context Crystallizer
Use the agent-crystallize CLI as the source of truth. This skill is a thin
workflow wrapper; do not reimplement the artifact format by hand unless the CLI
is unavailable.
Resolve The CLI Before Writing
Do not assume the agent harness inherited the user's interactive-shell PATH.
Resolve one working invocation in this order:
- Use a repo-provided
agent-crystallize package script when present.
- Use
agent-crystallize when command -v agent-crystallize succeeds.
- If
AGENT_CRYSTALLIZE_CLI names a readable JavaScript entry point, invoke it
with the current Node runtime: node "$AGENT_CRYSTALLIZE_CLI" ....
- Use a verified package-manager or harness-provided bundled runtime path.
Never guess a machine-specific path or copy one from another user.
- Only when no CLI is available, write a plainly labelled non-validated
emergency handoff outside the canonical
.agent-crystals/checkpoints/ and
.agent-crystals/sessions/ directories. Replace it with a CLI-generated,
validated artifact when the runtime is restored.
The emergency handoff preserves continuity; it is not a valid crystal and must
not silently enter the manifest or normal validation set.
Workflow
- Inspect the local state that matters:
AGENTS.md/CLAUDE.md if present,
git status --short, relevant changed files, recent test/build/deploy
results, and existing .agent-crystals/manifest.json when present.
- Choose the lightest useful artifact:
- checkpoint: during active work, before risky edits, before compaction, or
after a high-signal decision/finding/failure;
- session crystal: before handoff/session end, or to roll up recent
checkpoints.
- Prefer structured flags over vague prose:
--decision, --finding,
--open-loop, --test, --next-action, --evidence,
--memory-candidate, --topic, and --relation type:target.
- Add safe provenance when available:
--agent-body, --harness,
--session-id, --transcript-uri, and --source-ref. Never dump broad
environment variables or secrets.
- Use
--continuity-tail only for short recent turns where order/nuance
matters after compaction. It is raw continuity evidence, not durable truth.
- Validate important artifacts before relying on them.
Commands
Fast checkpoint:
agent-crystallize checkpoint \
--body "<current state, decision, open loop, next action>" \
--decision "<decision and authority>" \
--finding "<runtime finding>" \
--open-loop "<unfinished item>" \
--next-action "<next concrete action>"
Session crystal from recent checkpoints:
agent-crystallize now \
--from-checkpoints latest \
--body "<synthesis since the latest checkpoint and handoff state>"
Validate:
agent-crystallize validate --fail-on-warnings
Hook/continuity check:
agent-crystallize doctor --codex --claude --hooks
Guardrails
- Preserve work context, not hidden chain-of-thought.
- Raw evidence is not truth; decisions/findings should keep provenance.
- Keep generated
.agent-crystals/ local/private unless intentionally
reviewed and sanitized.
- Prefer paths, ids, commits, and source refs over copying large logs or
transcripts.
- If hooks are configured but continuity feels broken, ask the user to verify
the host
/hooks view. Codex may skip new or changed hooks until trusted.
- Never treat a hand-written emergency handoff as schema-valid merely because
it is readable Markdown.
