This directory contains modular AI agent instruction files for the GitLab
project. These files are referenced from AGENTS.md at the repository root
via .ai/... paths.
AGENTS.mdat the repo root (and optionally at subdirectory levels) is the entry point.- Each
AGENTS.mdhas aCLAUDE.mdnext to it that contains only the@AGENTS.mdimport. Claude Code skipsAGENTS.mdwhen aCLAUDE.mdorCLAUDE.local.mdexists, so the import keeps one set of instructions for all tools. Put instructions inAGENTS.md, not inCLAUDE.md. When you add anAGENTS.md, add theCLAUDE.mdtoo. - When you start Claude Code in a subdirectory, the imports in the parent
CLAUDE.mdfiles are external to the working directory. Approve them when Claude Code asks. Claude Code asks only once per project. If you decline, or if a non-interactive session has no earlier approval, Claude Code does not load the parent instructions. Start scripted runs, such asclaude -p, at the repository root. A non-interactive session cannot show the approval dialog. - The entry point references module files in
.ai/via.ai/<module>.md. - The
.ai/*pattern is gitignored, so you can add personal instruction files here without them being committed. Committed modules were added withgit add --force. Files already tracked by git (force-added) will continue to be tracked despite the gitignore pattern — only new untracked files you create in.ai/are automatically ignored.
.ai/
ci-cd.md # CI/CD pipeline guidelines
git.md # Git workflow guidelines
merge-requests.md # Merge request workflow guidelines
code-review.md # Code review methodology and standards
principles/ # SSOT-derived development principles
manifest.yml # Manifest: doc paths, file filters, baselines
distilled/ # Auto-generated principle files (one per manifest entry)
baselines/ # Hand-curated rules not yet in docs.gitlab.com
.claude/
skills/<name>/SKILL.md # Shared Claude Code skills (auto-discovered)
.agents/
skills -> ../.claude/skills # symlink, so other agents such as Duo and OpenCode
# pickup skills on session startup.
- Root
AGENTS.md: The Context Loading section routes task types to the hand-authored topical modules (.ai/git.md,.ai/merge-requests.md,.ai/ci-cd.md) and points domain-specific work at thegitlab-coding-principlesskill. - Directory-scoped
AGENTS.md: Files in target directories (e.g.,doc/AGENTS.md,workhorse/AGENTS.md) provide directory-specific guidance. Works with any AI tool that respects directory-scopedAGENTS.mdfiles. - Claude Code: Uses the project-scope skill at
.claude/skills/gitlab-coding-principles/SKILL.md, auto-discovered from.claude/skills/. - OpenCode and other AGENTS.md-aware tools: Use the same file via the
.agents/skillssymlink, which points at.claude/skills. No second copy to keep in sync.
Skills are auto-discovered by Claude Code from the project-root
.claude/skills/ directory — no install step is required. After
cloning, every committed skill is immediately available. The same
directory is exposed to other tools via the .agents/skills symlink.
.claude/ is gitignored at the project root, so shared skills are
committed with git add --force — the same pattern used for everything
in .ai/. See .claude/skills/README.md
for the directory layout and conventions.
To customize a shared skill for yourself without touching the team's version, create a personal-level copy at the same skill name under your home directory:
~/.claude/skills/<name>/SKILL.md
Claude Code resolves same-named skills across levels by precedence:
enterprise > personal > project
A personal-level skill takes precedence over the project-level one committed in this repo. See the Claude Code docs on where skills live and how precedence works for the full table.
Why not "override" at the project level by editing the file in place? The project-level files under
.claude/skills/are tracked by git viagit add --force. Once a path is tracked,.gitignoreno longer shields it: editing the working-tree copy is an ordinary uncommitted change, and any latergit pullthat advances the same path is refused witherror: Your local changes ... would be overwritten by mergeuntil you commit, stash, or discard. Use the personal-level path instead — it's a different file, so git never sees a conflict and Claude Code's precedence rule picks your version.
Create any .md file in .ai/ — it will be gitignored automatically:
# Example: add personal testing preferences
echo "# My Testing Notes" > .ai/my-testing.mdIf you wish, you can create these files in a separate source-controlled project, and symlink them into this repo.
To add a new shared module that all contributors benefit from:
- Create the file in
.ai/(e.g.,.ai/new-module.md) - Force-add it:
git add --force .ai/new-module.md - Reference it from
AGENTS.md - Commit
Create CLAUDE.local.md at the repository root for personal customizations.
AGENTS.md references it explicitly via Read @CLAUDE.local.md,
so every agent picks it up. It can in turn reference any additional gitignored
files you keep in .ai/ or elsewhere.
AGENTS.local.md is also gitignored and reserved for the same purpose, but
nothing references it today, so it will not be loaded unless you add a reference.
Neither file is committed. Both may be symlinked from a local source-controlled repo.
principles/README.md— How the SSOT sync worksAGENTS.md— Project-level entry point for all AI tools- https://gitlab.com/gitlab-org/gitlab/-/work_items/594821