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.
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.
### Skill Specification
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.
The two main specifications are:
1.**Directory structure:**
A skill is a directory containing, at minimum, a SKILL.md file:
```text
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
```
**SKILL.md format:**
The SKILL.md file must contain YAML frontmatter followed by Markdown content. The frontmatter includes metadata fields such as `name` and `description`, which are the most important for enabling automatic skill discovery by AI coding tools.
### Skill Development
Skills should be **modular** and **tested** — the same bar we hold for code.
#### Guideline 1: Modular
**One purpose per skill. Compose, don't bundle.**
A skill can be simple (`run_dbt_locally`, `gitlab-mr`) or an end-to-end workflow that chains skills together. What matters is that each skill has one clearly stated purpose, and any sub-task that could be its own skill *is* its own skill.
A skill called `build_and_open_mr` might call `run_dbt_locally` then `gitlab-mr` — that's modular. The orchestration logic lives in the workflow skill; the implementation logic lives in the sub-skills.
#### Guideline 2: Tested
**You ran it. It worked.**
A skill that hasn't been run end-to-end isn't ready to merge. That means:
1. You invoked it via the agent (not just read through the instructions)
1. The full workflow completed without the agent getting stuck or asking for unexpected clarification
1. The expected output was produced
The [agentic_skills_changes MR template](https://gitlab.com/gitlab-data/analytics/-/blob/master/.gitlab/merge_request_templates/python_changes.md?ref_type=heads) enforces both of these before merge.
## Agents
Agents are composed from skills and subagents. Each agent is defined by a markdown file that specifies:
@@ -50,7 +96,9 @@ As the field of agentic AI evolves rapidly, the team's conventions, tooling choi
The Data Team's skills are maintained directly in the repositories where they're used. Browse the skills directories to see what's available:
-**[Data Team agentic skills](https://gitlab.com/gitlab-data/data-team-agentic-skills)** - Shared skills that can be used across other data repositories rather than creating the same skill in each repo
-**[Analytics repository skills](https://gitlab.com/gitlab-data/analytics/-/tree/master/agents/skills?ref_type=heads)** - Skills for dbt, Snowflake, and analytics workflows
-**[Extract repository skills](https://gitlab.com/gitlab-data/extract/-/tree/main/agents/skills?ref_type=heads)** - Skills for data extraction and pipeline work
-**[Snowflake permissions skills](https://gitlab.com/gitlab-data/snowflake-permissions/-/tree/main/agents/skills?ref_type=heads)** - Skills to provision Snowflake users and roles via Permafrost
As of writing, there still are NOT many skills available, but we will be adding more regularly.
