Set up AI coding agents with the GitLab Orbit skill

The GitLab Orbit skill gives AI coding agents structured guidance for querying the GitLab Orbit graph. It includes:

• Query recipes - paste-ready queries for common questions, such as class inheritance, pipeline history, and grouped counts.
• Query language reference - syntax guidance for the enabled query mode: JSON Query DSL or read-only openCypher 9-based syntax.
• Troubleshooting - exit codes, empty-result diagnostics, and common pitfalls.
• Repository maps - the local repo-map command for a checkout. JSON mode also includes a helper script for GitLab Orbit Remote.

The skill works with both GitLab Orbit Remote and GitLab Orbit Local.

Prerequisites

• GitLab CLI (glab) v1.117.0 or later. It forwards glab orbit <command> to the GitLab Orbit binary it installs. If glab skills or glab orbit is not recognized, update glab first.

Install the skill

Install globally (available to every project):

glab skills install --global orbit

This installs the skill to ~/.agents/skills/orbit.

Install for the current project only:

glab skills install orbit

This installs the skill to .agents/skills/orbit in the project root.

If the skill is already installed, glab reports that SKILL.md exists and suggests --force to overwrite.

Claude Code does not scan .agents/skills. Link the skill into its own directory so it can find it:

ln -s ../../.agents/skills/orbit ~/.claude/skills/orbit

orbit setup writes the local skill and this link for you.

Update the GitLab Orbit skill

To update to the latest version, re-run the install command with --force:

glab skills install --global --force orbit

Use the wrapper skill

The orbit-wrapper skill copies no guidance. It runs glab orbit skills get orbit and loads the skill your GitLab instance serves, composed with your installed GitLab Orbit CLI, so it can’t drift from the binary. It needs glab and the GitLab Orbit CLI installed. Install it instead of the orbit skill, not alongside it. Install it with npx skills:

npx skills add https://gitlab.com/gitlab-org/orbit/knowledge-graph --skill orbit-wrapper

In Claude Code’s default permission mode, the skill can’t run its ! command and fails to load. Allow the command in ~/.claude/settings.json, or in the project’s .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(glab orbit skills get orbit)"]
  }
}

With that rule the skill loads without a prompt. Running Claude Code with --dangerously-skip-permissions also works.