openclerk

name	OpenClerk
description	Use installed openclerk document and openclerk retrieval JSON. With explicit user content or runner-supported public-source context, let the agent/OpenClerk propose path, title, body preview, tags, fields, and next approved request; do not write before approval. Bootstrap no-tools rule - if required fields, content/body, or update target are missing and no faithful candidate, duplicate-risk, artifact, or public-link placement proposal can be formed; if numeric limit is negative; or if bypass is requested with SQLite, raw vault/file/repo inspection, HTTP/MCP, legacy/source-built paths, unsupported transports, backend variants, module-cache inspection, rg, find, ls, external OCR, browser automation, local file reads, or opaque artifact parsing, this description is complete. For those invalid cases only, do not open this skill file, run commands, use tools, or call the runner; respond with exactly one no-tools assistant answer naming the missing/invalid fields or unsupported workflow, and ask for missing fields.
license	MIT
compatibility	Requires local filesystem access and an installed openclerk binary on PATH.

OpenClerk

Use this skill for routine local OpenClerk knowledge-plane tasks. The production interface is AgentOps: this Skills-compatible router plus the installed JSON runner.

openclerk capabilities
openclerk config
openclerk document
openclerk retrieval

SKILL.md is an activation, routing, and safety contract, not the durable home for long workflow recipes. Once a request is safely inside the runner contract, use agent autonomy with runner JSON results, runner rejections, returned agent_handoff, openclerk capabilities, and compact runner help. Repeated exact JSON, command ordering, or scenario-specific choreography is product UX evidence for a runner workflow-action comparison, not a reason to expand this file.

For the compact coding-agent contract in this source repo, see docs/agent-contract.md; keep routine procedure in runner help or runner-owned workflow actions rather than in this skill.

Action Index

Prefer a promoted workflow action over manual primitive choreography when it matches the request:

• Source-linked synthesis create/update, including disposable validation synthesis: document compile_synthesis once with user-provided target, title, source refs, and requested claims as body_facts or body text; then answer from compile_synthesis.agent_handoff.
• Disposable validation synthesis: document validation_synthesis_report once with validation_synthesis.disposable_validation=true when the runner is bound to a routine UX disposable vault copy; answer from its agent_handoff.
• Representative source discovery: retrieval source_discovery_report once; answer from source_discovery.agent_handoff, using categories/counts instead of private paths, titles, snippets, ids, or raw JSON for private telemetry.
• Source URL artifact/source inspection before durable write: document ingest_source_url with mode: "inspect" for runner-owned preview, discovered link candidates, duplicate status, and next approved requests; answer from source_url_intake_plan.agent_handoff.
• Source URL placement before durable fetch/write: document ingest_source_url with mode: "plan", then answer from source_placement_plan.agent_handoff.
• Harness-supplied web search planning: document web_search_plan, then answer from web_search_plan.agent_handoff; approved fetch/write remains ingest_source_url.
• Artifact candidate intake and explicit local OCR review: document artifact_candidate_plan, then answer from artifact_candidate_plan.agent_handoff; approved durable writes remain create_document or ingest_source_url.
• Vault structure stewardship: document plan_move_document first, or plan_path_cleanup for runner-owned name/path proposals; approved writes use move actions, never raw filesystem moves.
• Source-sensitive audit explain/repair: retrieval {"action":"source_audit_report","source_audit":{"query":"...","target_path":"...","mode":"explain|repair_existing","conflict_query":"...","limit":10}}, then answer from source_audit.agent_handoff.
• Records, decisions, provenance, and projection evidence bundles: retrieval evidence_bundle_report once; answer from evidence_bundle.agent_handoff.
• Decision-like record lookup across formal decisions, records, search, provenance, and projection freshness: retrieval decision_lookup_report once; answer from decision_lookup.agent_handoff.
• Duplicate update-versus-new clarification: retrieval duplicate_candidate_report, then answer from duplicate_candidate.agent_handoff.
• Workflow surface selection: retrieval workflow_guide_report, then use workflow_guide.agent_handoff to choose the next runner action.
• Routine read-only memory-router policy evidence reports: retrieval memory_router_recall_report, then answer from memory_router_recall.agent_handoff or returned evidence. For ordinary vault fact recall, use retrieval search instead.
• Structured data and non-document canonical-store decision support: retrieval structured_store_report, then answer from structured_store.agent_handoff; do not claim independent tables, external connectors, or structured writes.
• Hybrid/vector decision support: retrieval hybrid_retrieval_report, then answer from hybrid_retrieval.agent_handoff; do not claim vector ranking.
• Relationship graph context: retrieval graph_context_report; answer from graph_context.agent_handoff; canonical markdown is authority, graph evidence is navigation context, and there is no graph truth/ranking/memory.
• Relationship paths, direct-vs-derived evidence, typed candidates, or limited graph audits: retrieval graph_relationship_report; answer from graph_relationship.agent_handoff; typed candidates are cited suggestions.
• Approval-gated canonical markdown relationship maintenance plans: retrieval graph_relationship_maintenance_plan; answer from handoff; review exact next replace/append request before any durable write.
• Explicit local semantic retrieval: retrieval semantic_search, then answer from hits/handoff; requires explicit recall, loopback Ollama, no Gemini fallback, and unchanged default search.
• Retrieval regression: use retrieval_eval_capture only when explicitly requested, then retrieval_eval_replay; local JSONL stores sanitized query/action/filter/result refs and provider posture, not writes/snippets/raw vault content.
• Search diagnostics: retrieval search_diagnostics_report; answer from handoff with search vs explicit semantic_search, module readiness/cost/latency posture, and no default ranking change.
• Maintenance posture: retrieval maintenance_report; answer from handoff with layout, projection, relationship, duplicate, module, and git posture; no cron, background jobs, repair, or writes.

Use lower-level primitives for explicit primitive requests, advanced/manual cases, unsupported workflow-action inputs, and follow-up inspection after a runner rejection. For promoted workflow actions, answer from the first successful returned handoff; do not repeat the same action or inspect follow-up primitives unless the result rejects or the user asks for more.

Core Guardrails

• Answer routine OpenClerk requests only from runner JSON results. Use the configured environment; pass --db only when the user explicitly names a dataset.
• When the user says runner and data path are configured, skip setup checks (command -v, --version, resolve_paths, capabilities, skill path).
• Treat every runner path as vault-relative, such as notes/projects/example.md, sources/example.md, or synthesis/. Never use storage roots, machine-absolute paths, .openclerk-eval/vault, or OS-specific backslash/drive paths in runner JSON or committed OpenClerk document paths.
• Do not inspect source files, generated artifacts, backend variants, module-cache docs, SQLite, vault files, or .openclerk-eval/vault directly for routine tasks. Do not use repo search, rg --files, find, ls, openclerk --help, HTTP/MCP, legacy/source-built paths, unsupported transports, browser automation, external OCR, PPTX parsing, email/chat/form/bundle parsing, direct local file reads, or external acquisition tools as substitutes for runner JSON.
• Parallelize only safe reads: path/list/get/layout, retrieval reads, source_audit_report explain, and audit_contradictions plan_only. Sequence writes: init, document writes, compile_synthesis, repair modes.
• Durable writes require explicit approval for proposed path/title/body, placement, or update-versus-new choice; public read/fetch/inspect is not durable-write approval.
• Honor persisted or supplied autonomy profiles: approval_mode, drafting_mode, write_target_mode, citation_mode, privacy_mode, and audience_mode. openclerk config inspect_config reports effective storage, profile, module, and git gate posture; configure_profile/clear_profile are the only profile writes. Request autonomy overrides persisted defaults field-by-field. propose_only blocks durable writes; trusted/disposable modes still need an appropriate target.

No-Tools Before Runners

Before runners, answer exactly once with no tools when missing content, missing update target, missing retrieval/source/video fields, low confidence, a negative numeric limit, or a Core Guardrails bypass makes runner-backed planning impossible. Ask for missing content or target fields by name, or reject the invalid/unsupported workflow and point back to the OpenClerk runner contract.

For strict document creation without enough content or context for proposal-first planning, answer: missing path, title, and body; please provide them. Do not call validate, create_document, or discovery.

Proposal-first defaults are valid runner-backed work when explicit user content or runner-supported public-source context is present:

• document create/validate with omitted path, title, tags, fields, or final body may propose a faithful candidate before any write; explicit user values win
• artifact and note intake should use artifact_candidate_plan when omitted path/title/body preview/tags/fields, confidence, duplicates, or create/ingest handoff need one runner-owned plan
• duplicate-risk checks may use runner-visible retrieval/list/get/provenance evidence before choosing update versus new
• public-link inspection may fetch a supplied public URL through the runner, propose related source candidates, and still require approval before durable source writes

Opaque screenshots, images, slide decks or PPTX files, email archives, exported chats, forms, and bundles are unsupported as opaque input unless the user pasted preservable text/body content or requested runner-backed OCR review for a local image/PDF path. Do not claim parser truth, external OCR results, hidden file inspection, attachment contents, or bundle contents not returned by the runner.

Workflow Policies

Keep workflow-specific procedure out of this skill. Apply these compact policies and let runner results drive the answer:

• Candidate documents and artifacts: preserve explicit user path/title/body/type/tag/field/naming instructions; choose omitted path, title, body preview, tags, and fields from explicit content or runner-supported public-source context by default; use artifact_candidate_plan when tags, fields, confidence, duplicate status, or create/ingest handoff are relevant; otherwise validate with openclerk document before presenting a candidate; show Path:, Title:, and Body preview:; state no document was created; ask for approval before durable writes; for note-like candidates without an explicit path, use notes/candidates/<slug-from-title>.md, derive a concise singular noun phrase title, and Include type: note frontmatter plus a # <Title> heading.
• OCR artifact review: text-extractable documents do not need OCR; use OCR review only for common images, scan-only PDFs, or PDFs whose embedded text is bad or partial, and treat returned OCR text as candidate evidence until durable-write approval.
• Duplicate checks: when duplicate risk is requested or plausible, use runner-visible evidence before validating or writing; report the likely target, evidence inspected, and that no document was created or updated; ask whether to update the existing target or create a confirmed new path.
• Public URL/source intake: use web_search_plan for supplied search results and ingest_source_url for HTTP/HTTPS PDF and public web sources. Use mode: "inspect" when the agent should inspect a supplied public URL, extract a preview, and propose related source candidates; use mode: "plan" only for no-fetch placement. Do not fetch URLs with browser, HTTP, filesystem, or other non-runner tools; ask for approval before durable source writes.
• Video/YouTube source intake: use ingest_video_url only with user-supplied transcript text and provenance; do not acquire media or transcripts externally.
• Document lifecycle review, rollback, restore, and semantic diff: stay inside openclerk document and openclerk retrieval. Use git_lifecycle_report only for local Git status/history/checkpoints; it is storage history, not semantic provenance, and checkpoint mode needs explicit runner config. Existing-document write receipts return compact diffs, preimage hashes, and replace_document rollback requests; avoid raw vault edits for repair.
• Messy populated-vault retrieval: answer from runner-visible authority such as metadata-filtered authority results, active canonical sources, cited source paths, doc_id, and chunk_id; treat polluted, decoy, stale, draft, archived, duplicate, or candidate documents as non-authority unless runner-visible source authority says otherwise.
• Synthesis maintenance: prefer compile_synthesis; include requested outcome claims in body_facts or body; use lower-level document and retrieval actions only for explicit primitive or manual cases; preserve source_refs, ## Sources, ## Freshness, provenance, and projection freshness. Detailed versions of these workflows belong in runner actions, compact runner help, maintainer/eval docs, or follow-up candidate-surface comparisons.

Document Tasks

Run document tasks with:

openclerk document

Common actions are validate, create_document, ingest_source_url, ingest_video_url, web_search_plan, artifact_candidate_plan, plan_move_document, move_document, rename_document, promote_candidate, plan_path_cleanup, list_documents, get_document, append_document, replace_document, replace_section, resolve_paths, inspect_layout, compile_synthesis, validation_synthesis_report, and git_lifecycle_report. Use openclerk document --help for request shapes.

Move actions use move with doc_id or path plus target_path; plan_path_cleanup proposes exact next requests and apply mode needs autonomous trusted/disposable. Writes refuse existing targets; rename_document is same-directory only; promote_candidate leaves notes/candidates/.

Validation rejections use rejected: true; runtime failures exit non-zero.

Retrieval Tasks

Run retrieval tasks with:

openclerk retrieval

Common actions are search, document_links, graph_neighborhood, records_lookup, record_entity, services_lookup, service_record, decisions_lookup, decision_record, provenance_events, projection_states, audit_contradictions, source_audit_report, source_discovery_report, evidence_bundle_report, decision_lookup_report, duplicate_candidate_report, workflow_guide_report, memory_router_recall_report, structured_store_report, hybrid_retrieval_report, graph_context_report, graph_relationship_report, graph_relationship_maintenance_plan, semantic_search, retrieval_eval_capture, retrieval_eval_replay, search_diagnostics_report, and maintenance_report. Use openclerk retrieval --help for promoted workflow-action request shape.

Use search for source-grounded answers; document links/graphs for markdown relationships; records/services/decisions for promoted projections; provenance for derivation; projection states for freshness. Canonical markdown remains authoritative over derived service, record, decision, and synthesis projections.

Minimal request shapes:

{"action":"search","search":{"text":"authority evidence","metadata_key":"status","metadata_value":"active","limit":10}}
{"action":"provenance_events","provenance":{"ref_kind":"document","ref_id":"doc_id_from_json","limit":20}}
{"action":"projection_states","projection":{"ref_kind":"document","ref_id":"doc_id_from_json","limit":20}}

Deferred Capability Evidence

Deferred-capability comparison, revisit, or promotion-decision questions are valid runner-backed evidence tasks when the user asks what existing OpenClerk documents and retrieval results can prove. Use installed openclerk document and openclerk retrieval JSON to inspect runner-visible documents, citations/source refs, provenance, and projection freshness.

Treat memory transports, remember/recall, autonomous router APIs, vector DBs, embeddings, graph memory, and new runner actions as unsupported only when the user asks you to use, implement, or rely on them as routine OpenClerk surfaces.

Answering From Results

Answer the user's substantive question from selected runner JSON fields before listing evidence. Preserve citation paths, source refs, doc ids, chunk ids, provenance, projection freshness, validation boundaries, and authority limits for source-sensitive claims. For retrieval-only repeats, confirm no durable write only when asked, but still restate the answer and citations.