omnigraph-best-practices

omnigraph-best-practices is a packaged skill that captures the day-to-day operational rules for working with a locally deployed Omnigraph (RustFS-backed or remote S3). 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|schema|embed|branch|commit|run commands, .pg schema files, .gq query files, s3://omnigraph-local/... URIs, 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

The six rules

The skill enforces six operational conventions:

1. Lint before commit — omnigraph query lint --schema schema.pg --query queries/foo.gq validates both sides against each other. No running repo 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; 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.

What it covers

• Local RustFS setup and AWS env vars
• Project layout conventions around omnigraph.yaml
• Schema authoring and evolution (plan before apply)
• Query linting
• Data changes: change vs load --mode merge vs load --mode overwrite
• Branches for data review
• Embeddings
• Aliases for automation
• HTTP server operation
• Cedar policy
• Common gotchas (port collisions, missing AWS vars, PATH issues)

Installing

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

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

Reference

• Full SKILL.md: skills/omnigraph-best-practices/SKILL.md
• Human-readable version: docs/best-practices.md