Use Orbit (`glab orbit` or `orbit`) to search code and read it with callers and tests. It reads MRs, issues, and failed jobs with the code they cite. Graph queries answer relationship and aggregation questions across GitLab. Skip it for writes that `glab` handles.
79%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./skills/orbit/SKILL.mdQuery GitLab Orbit (previously GitLab Knowledge Graph) through the flat glab orbit command tree. It needs glab v1.126.0 or later. Hosted commands handle authentication, response framing, and exit codes. Local commands use the managed binary and the local DuckDB graph.
If a glab orbit command fails with "command not found", an auth error, or a feature-flag exit code, work through the first-run setup.
If guidance is wrong or outdated (command, flag, or behavior), tell the user.
With their confirmation, open a focused MR against metadata.source-project fixing metadata.source-path (one fix per MR, Conventional Commits).
If they decline, note the discrepancy in one line and continue with the corrected command.
Queries use read-only openCypher 9-based syntax (MATCH ... RETURN). If you find a legacy JSON query, run glab orbit skills get orbit-gql-migration to convert it.
glab orbit help and glab orbit <command> --help are the authoritative usage references. Run glab orbit skills to list available skills. Run glab orbit skills get orbit to print the composed skill (SKILL.md by default), or append a path such as references/local/cli.md to print a file.
Run CALL db.schema() once per session, because the schema does not change mid-session. It lists every relationship as (Source)-[:TYPE]->(Target) and the properties of the common nodes, such as User, Project, Group, MergeRequest, and WorkItem. Run CALL db.schema('Node') only for a node it does not list properties for. Query syntax and paste-ready queries are in references/gql.md.
Batch schema reads: make every schema read a question needs in one shell command, not one command per read. Each CALL db.schema call takes one node. On the first read, chain the overview with the nodes that the question names. Later, batch only the new node reads.
glab orbit query 'CALL db.schema()'; echo; glab orbit query "CALL db.schema('Vulnerability')"; echo; glab orbit query "CALL db.schema('Pipeline')"The named-query catalog at GET /api/v4/orbit/query/templates is rendered in your mode. Do not reuse discovery results across users or mode changes. Entries contain only name, description, and raw_query; there is no client language selector. See catalog troubleshooting.
Each glab orbit query has fixed per-call overhead. Prefer one aggregate query, with count(...) in RETURN, over N lookups for "how many X grouped by Y", and batch related lookups.
When editing Orbit docs or skills, fence executable GQL queries as gql orbit-query so docs smoke tests run them.
Pass query text inline. The CLI builds the request envelope, so a short query needs no temporary file:
glab orbit query 'CALL db.schema()'
glab orbit query "CALL db.schema('Project')"
glab orbit query "MATCH (p:Project {full_path: 'gitlab-org/gitlab'}) RETURN p.id, p.full_path LIMIT 1"With a standalone install, use orbit query instead of glab orbit query. Quote the whole query for the shell; single-quoted string literals then need double quotes around the query.
--file reads a JSON request envelope whose query field holds the query text, not a bare query file. --file - reads that envelope from stdin. Default output is llm (compact, agent-friendly). Pass --response-format raw to pipe into jq. Endpoints are user-scoped, so do not pass -R owner/repo.
Read references/gql.md before you construct a query. These traps recur:
LIMIT does not bound the scan, so MATCH (p:Project) RETURN p LIMIT 5 rejects.-[:AUTHORED]->. -[AUTHORED]-> declares a variable and rejects.source: 'merge_request_event' filter.HAS_DIFF; see file history. Use HAS_LATEST_DIFF for one MR's current revision.WorkItem node. There is no Issue node.OR, XOR, RETURN DISTINCT, count(*), OPTIONAL MATCH, or WITH. DISTINCT works only inside count(): count(DISTINCT pl).orbit-package-registry skill first: glab orbit skills get orbit-package-registry.Resolve a user question in at most 5 query attempts, validation errors included. Changing only the row limit or the returned properties is not progress. Full rules: references/troubleshooting.md.
Orbit answers come from graph queries, not an authoritative source. Flag known coverage gaps inline when they affect the result. Full guidance: references/reporting.md.
glab orbit downloads, verifies, and runs the GitLab Orbit CLI binary from the orbit-cli package (macOS, Linux, and Windows). grep and context read the local graph and index the working tree on their own. workspace groups the other local-graph commands (index, list, reset). The top-level index and list still run as deprecated aliases. query, status, and schema call the GitLab Orbit API.
glab handles --install, --update, and --yes itself and forwards everything else to the binary. --install and --update are mutually exclusive. --yes skips the confirmation prompts, so pass it in scripts and agent runs. Put these flags before the subcommand (glab orbit --yes status); the binary rejects --yes after other subcommands, except for setup and uninstall, which take their own. glab's own update command also takes --yes. glab help orbit shows the wrapper help. glab orbit help and glab orbit <command> --help show the binary's.
glab orbit --install --yes # install without running
glab orbit --update # install the latest compatible versionSkip the confirmation prompts for good with glab config set orbit_cli_auto_run true and glab config set orbit_cli_auto_download true. Point glab at your own build with glab config set orbit_cli_binary_path /path/to/orbit or the GLAB_ORBIT_CLI_BINARY_PATH env var. That skips download, version checks, and updates. glab records orbit_cli_binary_version, orbit_cli_binary_checksum, and orbit_cli_last_update_check itself. Do not set them by hand.
| Topic | Location |
|---|---|
| First-run setup, exit codes, service health, iteration budget | references/troubleshooting.md |
| openCypher 9-based syntax and paste-ready queries | references/gql.md |
| Empty results and query validation errors | references/gql.md |
| Reporting results and coverage caveats | references/reporting.md |
| Maintaining this skill (contributing, doc sync) | references/maintaining.md |
gitlabhq/orbit-knowledge-graph
df9d9a3
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.