The Data Team's approach to agentic tooling is built around a **skills-first, compose-upward** model. Rather than building monolithic agents, the team decomposes work into small, testable, reusable **skills** — each handling a single well-defined task. Agents are then composed from those skills, delegating to them based on the type of work requested.
This approach builds on emerging standards from [OpenCode](https://opencode.ai) and Anthropic — including conventions like `AGENTS.md` for repository-level agent context — and will be continuously evaluated and evolved as GitLab Duo matures as a platform.
## Directory Structure Convention
Every repository that adopts this pattern organizes agentic tooling under an `agents/` directory with four subdirectories:
```console
agents/
├── memory/ #Shared context files for coordinating parallel agent work
├── skills/ #Atomic, reusable capabilities; each skill has a SKILL.md
└── agents/ #Composed agents ready for use; each agent has a markdown spec
```
## Skills
Skills are the atomic building blocks. Each skill lives in its own directory with a `SKILL.md` that defines its purpose, inputs, process steps, and constraints. Skills are scoped to a single responsibility and are designed to be invoked by agents or directly by engineers.
The team's skills follow the emerging [Agent Skills specification](https://agentskills.io/specification), an open standard that defines a portable, interoperable format for packaging AI agent capabilities. By conforming to this specification, skills can be discovered, loaded, and executed consistently across different AI coding tools and clients — making them portable beyond any single platform.
## Agents
Agents are composed from skills and subagents. Each agent is defined by a markdown file that specifies:
-**System prompt** — the agent's role and behavioral constraints
-**Skills** — which atomic skills it may invoke
-**Subagents** — which peer agents it may delegate to
-**MCP servers** — which external tools (databases, APIs, knowledge bases) it has access to
-**Process** — a structured workflow the agent follows
Agents are designed to be transparent and auditable: all capabilities are explicitly enumerated and no agent improvises outside its defined toolset.
## Development and Change Management
New skills and agents are validated before being promoted to production using tools like Anthropic's [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator), which provides a structured framework for evaluating, testing, and benchmarking skills prior to merging. This ensures that only well-tested, reliable capabilities are promoted to the `skills/` and `agents/` directories.
Once ready, changes follow the same merge request workflow as any other code change in the repository, ensuring peer review, version history, and rollback capability. Because skills and agents are plain markdown files, they are diffable, reviewable, and auditable like any other code artifact.
The `AGENTS.md` file at the repository root serves as the entry point for agentic context — it describes the directory structure and conventions so that any AI coding assistant working in the repository can orient itself immediately.
As the field of agentic AI evolves rapidly, the team's conventions, tooling choices, and agent designs will be continuously re-evaluated. Patterns that work well today may be superseded by new capabilities in GitLab Duo or updated standards from the broader ecosystem, and the team will adapt accordingly.
