# Onboard Team Area
> Onboard a new team or reserve a new code area in the Databricks CLI: add the team to .github/OWNERTEAMS, reserve experimental// and acceptance/experimental//, and map both paths in .github/OWNERS so the maintainer-approval gate routes the area's PRs to the team. Use when the user says 'onboard a team', 'add an OWNERS team', 'reserve an experimental area', 'add a new team to the CLI', or wants a new owned directory wired into review.
- Skill: `databricks/onboard-team-area` (Agent Skill)
- Install (CLI): `npx skillmds@latest add databricks/onboard-team-area`
- Raw SKILL.md: https://api.skillmd.com/api/skills/databricks/onboard-team-area/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: databricks (https://skillmd.com/u/databricks)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/databricks/onboard-team-area
---
# Onboard a team / area into the CLI
How ownership works here: `.github/OWNERS` is CODEOWNERS-style and last-match-wins. `.github/OWNERTEAMS` maps `team:` to an explicit `@member` list and is the source of truth, because the CI token cannot resolve GitHub org-team membership. The `maintainer-approval` workflow is a required check that blocks merge until every owned group a PR touches has at least one approval from one of its owners.
Worked example: PR #5605 ("Add ai-training OWNERS team and reserve experimental/air") is exactly the steps below: +1 line in OWNERTEAMS, two `.gitkeep` files, +2 lines in OWNERS.
## Inputs (ask if missing)
- Team alias, e.g. `ai-training`, and the `@member` list.
- Area/dir name, e.g. `air`.
- Experimental or stable? This decides where code lands (see the last section).
## Step 1 — Add the team to `.github/OWNERTEAMS`
Append one line, keeping the existing column alignment:
```
team: @member1 @member2 ...
```
If the team has a GitHub team page, add its URL to the header comment block. Skip the URL if the team page does not exist yet; the validator only warns about a missing URL, it does not block.
## Step 2 — Reserve the directories
Create empty `.gitkeep` placeholders so the owned paths exist before any code lands:
```
experimental//.gitkeep
acceptance/experimental//.gitkeep
```
## Step 3 — Map the paths in `.github/OWNERS`
Add rules under an `# ` comment. Because last-match-wins, specific rules go after the `*` maintainer catch-all:
```
/experimental// team:
/acceptance/experimental// team:
```
## Step 4 — Validate and open the PR
```bash
# OWNERS parser + approval-logic tests
node --test .github/scripts/owners.test.js .github/workflows/maintainer-approval.test.js
# OWNERS/OWNERTEAMS consistency: undefined teams, zero-owner rules, missing paths
node .github/scripts/owners.js validate
# Repo quick checks (no Go/Python/YAML changed, so the formatters have nothing to do)
./task checks
```
No `.nextchanges/` entry; this is ownership/config only. Write the PR using the `.github/PULL_REQUEST_TEMPLATE.md` sections (Why / Changes / Tests).
## Experimental vs stable, and graduation
- **Experimental** — code under `experimental//`, tests under `acceptance/experimental//`. Register it under the hidden parent in `cmd/experimental/experimental.go`, or top-level in `cmd/cmd.go` with `Hidden: true` (as `ssh` does). Experimental commands still ship enabled in every release; `Hidden` only removes them from `--help`, it does not gate or compile them out. No `.nextchanges/` entries while experimental. To hand a build to testers, push a `bugbash-` branch (auto-builds a snapshot) and share the `internal/bugbash/exec.sh` one-liner.
- **Graduating to stable** — `git mv` the feature-complete commands to `cmd//` + `libs//`, register them top-level in `cmd/cmd.go`, keep the old `experimental` paths as deprecated cobra aliases (`sub.Hidden = true`, `sub.Deprecated = '...'`), add OWNERS rules for the new stable paths, and add a `.nextchanges/` entry. See `experimental/aitools` graduating to top-level `aitools` (PR #4917) as the worked example.