omnigraph-best-practices

omnigraph-best-practices is a packaged skill that captures the day-to-day operational rules for working with Omnigraph. Local RustFS, S3-backed, or remote bearer-authed HTTP. Load it whenever an agent is authoring schema, writing queries, loading data, evolving schema, or automating graph operations.

When to use it

The skill activates on any of: omnigraph init|read|change|load|ingest|schema|embed|branch|commit commands, .pg schema files, .gq query files, s3://omnigraph-local/... URIs, remote bearer-authed graph endpoints, 504 errors against a graph, or work inside a folder containing omnigraph.yaml.

It is especially important to load this skill before:

• Running schema apply. Always schema plan first
• Running load. Pick --mode carefully
• Editing a .gq or .pg file. Lint afterward
• Writing to a remote graph. Verify via commit list afterward

The seven rules

1. Lint before commit, omnigraph query lint --schema schema.pg --query queries/foo.gq validates both sides against each other. No running graph required.
2. Plan before apply. Never run schema apply without a successful schema plan first. Apply is destructive; plan is free.
3. Branches are for data; apply is for schema. Review data ingests on a feature branch, then merge. Schema changes go straight to main.
4. Pick the right write command, change for typechecked, parameterized edits; load --mode merge for bulk upsert on local graphs; ingest for remote graphs; load --mode overwrite only for clean slates.
5. Parameterize everything. Never string-interpolate values into .gq bodies or --params. Declare $var: Type and pass via --params.
6. Expose agent operations as aliases. Not raw CLI invocations. Aliases decouple operation names from query implementations.
7. Verify after every remote write. Compare commit list --branch main head before and after. The CLI's exit code is not authoritative on remote graphs; proxies can drop the response while the write commits server-side.

Five Ontology Design Criteria (Gruber 1993)

Omnigraph schemas are ontologies. The skill applies Gruber's canonical criteria from Toward Principles for the Design of Ontologies Used for Knowledge Sharing directly to .pg authoring:

• Clarity. Precise type names, narrow enums over String, @check / @range for stated invariants. A reviewer should understand the domain from the schema alone.
• Coherence, @card, @unique, and edge directionality should not let the schema distinguish things the domain treats as equal.
• Extendibility. Prefer interfaces for shared shape; leave enums open where the domain admits more.
• Minimal encoding bias. Don't type dates as String because the source API returned strings; separate conceptual entities from surface encoding.
• Minimal ontological commitment. Don't add required properties or @card(1..1) "in case"; tighten later via schema plan when a real constraint emerges.

Gruber's resolution to the inevitable trade-off: having decided a distinction is worth making, give it the tightest possible definition.

The skill also references the twelve schema authoring principles in the cookbook's docs/omni-schema.md.

Provenance is structural

When Omnigraph serves as canonical truth across multiple agents, every assertion must answer who said it, when, based on what evidence. The skill recommends modeling provenance as a first-class Claim-style interface or node with required asserted_by, asserted_at, evidence_source, and optional confidence. Never as a free-text source: String or a metadata: JSON dump. Structured provenance is queryable, indexable, and migratable; free-form is none of these.

Deep-dive references

The skill ships eight self-contained reference files. Load only what you need:

Common gotchas the skill knows about

A non-exhaustive sample from the skill's trap table. Load it before debugging any parse or runtime error:

• # comments in .pg. Use //
• [Category] (list of enum). Use [String]; list elements must be scalars
• nearest() / bm25() / rrf() without limit. Compile error
• Config uses targets: / target:. Rename to graphs: / graph:
• omnigraph load against a remote URI. Use ingest for remote graphs
• Blind retry after 504 against a remote graph. Duplicates append-only nodes; check commit list --branch main head first

Edge traversal casing

Schema declares edges in PascalCase (FormsPattern), but queries traverse them in lowerCamelCase:

match {
    $s: Signal
    $s formsPattern $p       // edge FormsPattern: Signal -> Pattern
}

Installing

npx skills add ModernRelay/omnigraph-cookbooks@omnigraph-best-practices

Requires omnigraph CLI >= 0.3.1 and Docker (for local RustFS).

Reference

• Full SKILL.md: skills/omnigraph-best-practices/SKILL.md
• Human-readable operational guide: docs/best-practices.md
• Schema design principles: docs/omni-schema.md