CodeNorm

Agent Skill that mines your project's merged MR review history via GitLab Orbit to automatically derive your team's real coding standards, then enforces them against every diff, with zero manual setup

Comment

Inspiration

Every developer has experienced the frustration of getting review comments like "we don't do it this way here" feedback that reveals an unwritten team standard that nobody documented. Coding standards exist in every team, but they live scattered across old review threads, people's memories, and outdated wiki pages that nobody reads. We wanted to answer one question: what if an AI agent could learn your team's real standards directly from your MR history and then enforce them automatically on every new change?

What it does

CodeNorm is a GitLab Duo Agent Skill that works in two phases. Bootstrap run once. CodeNorm uses the GitLab Orbit Knowledge Graph to traverse your project's last 50 merged MRs, mining human reviewer comments via the MergeRequest → HAS_NOTE → Note graph relationship. It analyzes recurring patterns across naming, structure, error handling, testing, documentation, security, performance, and style and writes them into a living .gitlab/duo/STANDARDS.md file in your repository. Check run on every diff. CodeNorm reads your STANDARDS.md, loads your current diff, and reports any violations with the exact file path and line number. It only flags clear, specific violations ambiguous cases are skipped. The result is a project-aware, language-agnostic standards enforcer that knows your team's actual conventions not generic rules someone copied from the internet.

How we built it

CodeNorm is built as a SKILL.md Agent Skill on the GitLab Duo Agent Platform, following the Agent Skills specification. The core of the skill is a two-phase workflow defined in skills/orbit/SKILL.md with supporting reference files: Orbit query — we use glab orbit remote query to traverse MergeRequest → HAS_NOTE → Note relationships across 50 merged MRs, filtering out system notes (system: false) to keep only human reviewer comments Pattern extraction - the agent analyzes the returned notes and extracts patterns appearing in 3 or more distinct MRs, ensuring only real team standards are captured Standards file - derived standards are written to .gitlab/duo/STANDARDS.md as a committed, reviewable artifact Diff check - on subsequent runs, the agent loads the standards file and evaluates the current diff against each standard The skill is language-agnostic by design - it derives standards from your team's actual review behaviour, not hardcoded rules.

Challenges we ran into

Frontmatter validation — the GitLab Duo CLI is strict about SKILL.md frontmatter format. Moving slash-command to the top level (not nested under metadata) was required for the skill to load correctly. Windows TUI rendering — the Duo CLI TUI requires a proper terminal. The VS Code integrated terminal on Windows does not support the kitty protocol, causing the CLI to exit silently. Switching to Windows Terminal resolved this. Beta features access — the Duo CLI requires experiment and beta features to be enabled on a GitLab group namespace, not a personal namespace. Creating a dedicated group and enabling the toggle was a necessary setup step. Orbit note coverage — very recent notes (under 24 hours) may not yet be indexed by Orbit. We documented this as a known coverage gap in the skill's reference files.

Accomplishments that we're proud of

Built a fully working end-to-end Agent Skill that loads, bootstraps, and enforces standards in a live Duo CLI session Successfully mined real reviewer patterns from the gitlab-community/gitlab-org/orbit/knowledge-graph community codebase Designed a skill that is genuinely language-agnostic — it works on any project regardless of stack Orbit is not decorative in this skill — the bootstrap phase is only possible with Orbit's graph traversal. Single-entity GitLab API calls cannot replicate it Produced a reusable, committable artifact (STANDARDS.md) that any team can review, edit, and version-control

What we learned

The GitLab Orbit Knowledge Graph is a powerful primitive for SDLC intelligence , traversing relationships across MRs, notes, users, and files opens up use cases that are impossible with REST APIs alone. Agent Skills are a lightweight but expressive way to give Duo specialized domain knowledge without building a full flow or agent The system: false filter on Note entities is critical , without it, GitLab system notes flood the results and pollute the standards derivation Real team standards emerge from repetition, requiring a pattern to appear in 3+ distinct MRs before including it produces much higher quality output than including everything

What's next for CodeNorm

Auto-refresh : trigger a standards refresh automatically when a configurable number of new MRs are merged, keeping STANDARDS.md always up to date Per-directory standards : derive different standards for different parts of the codebase (e.g. stricter rules for src/security/ than scripts/) Standards diff reporting : when refreshing, show exactly what changed vs. the previous version so teams can review the evolution of their conventions MR integration : run the check phase automatically when a new MR is opened, posting violations as inline review comments via the Code Review Flow AI Catalog publishing : publish CodeNorm to the GitLab AI Catalog so any team can enable it in their project with one click

Built With

  • agent-skills
  • clickhouse
  • gitlabduo
  • gitlabduoagentplatform
  • gitlabduocli
  • gitlabknowledgegraph
  • gitlaborbit
  • glab
  • markdown
  • skill.md
Share this project:

Updates