feat: Breeze-aware AI agent skills system (GSoC 2026 PoC)

.agents/skills/run-static-checks/SKILL.md

@@ -0,0 +1,89 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+      https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- markdownlint-disable MD022 -->
+---
+name: run-static-checks
+description: Run prek (pre-commit) static checks including ruff linting, formatting, and type checks on Airflow code. Works identically on host and inside Breeze.
+---
+<!-- markdownlint-enable MD022 -->
+
+Run Static Checks
+=================
+
+Run the Airflow pre-commit pipeline (`prek`) to lint, format, and type-check changed
+files. This must pass before any PR is merged.
+
+Source of truth for this workflow is `contributing-docs` contributor guidance; the
+commands below are the Breeze-aware execution mapping for agents.
+
+Context Detection
+-----------------
+
+`prek` is installed both on the **host** and inside **Breeze**. The command is
+identical in both environments — no context switching is needed.
+
+Commands
+--------
+
+```bash
+# Run all checks on files changed since main (standard pre-PR flow)
+prek run --from-ref main --stage pre-commit
+
+# Run slower manual checks too
+prek run --from-ref main --stage manual
+
+# Run only ruff linting
+prek run ruff --from-ref main
+
+# Run only ruff formatter
+prek run ruff-format --from-ref main
+
+# Run a single check by hook ID (e.g. mypy)
+prek run mypy --from-ref main
+```
+
+Workflow Context
+----------------
+
+This is **Scenario 1, Step 2** of the standard Airflow contributor workflow:
+
+1. stage-changes
+2. → **run-static-checks** (this skill)
+3. run-unit-tests
+
+Always run static checks **before** running unit tests to catch simple formatting
+or import errors early.
+
+Prerequisites
+-------------
+
+- Changes must be staged (`git add`) before running — see the `stage-changes` skill.
+- `prek` must be installed: `uv tool install prek`
+- Hooks must be enabled: `prek install`
+
+Interpreting Failures
+---------------------
+
+| Exit Code | Meaning |
+|---|---|
+| 0 | All checks passed |
+| 1 | One or more checks failed — read the output to identify which hooks failed |
+
+When a check fails, `prek` prints the hook name and the specific files/lines that
+failed. Fix the reported issues and re-run. Many hooks (ruff, ruff-format) auto-fix
+on first run — check `git diff` after failure to see auto-fixes.
+
+Common Issues
+-------------
+
+- **`ruff` lint error:** Fix manually based on the error message, then re-stage and retry.
+- **`ruff-format` failure:** Run `uv run ruff format <file>` then re-stage and retry.
+- **`mypy` type error:** Fix the type annotation issue flagged by the error message.
+- **`check-xml` / other infra checks:** Usually auto-fixed by the hook itself.
+
+Success Criteria
+----------------
+
+`prek run --from-ref main --stage pre-commit` exits with code 0 and prints
+`Passed` for every hook.

.agents/skills/run-unit-tests/SKILL.md

@@ -0,0 +1,109 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+      https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- markdownlint-disable MD022 -->
+---
+name: run-unit-tests
+description: Run Airflow unit tests with context-aware command selection. Uses uv on the host and breeze run inside the container. Supports targeted test paths to avoid running the full suite.
+---
+<!-- markdownlint-enable MD022 -->
+
+Run Unit Tests
+==============
+
+Run a targeted subset of Airflow unit tests. The correct command differs depending
+on whether you are running on the **host** or inside a **Breeze** container.
+
+Source of truth for test workflow semantics is `contributing-docs`; this skill maps
+that guidance into context-aware host/Breeze command execution.
+
+Context Detection
+-----------------
+
+Check for the `BREEZE` environment variable before choosing a command:
+
+```bash
+# You are inside Breeze if this variable is set:
+echo $BREEZE
+```
+
+| Context | Detection | Command |
+|---|---|---|
+| **Host** | `BREEZE` absent | `uv run --project <PROJECT> pytest <path>` |
+| **Breeze** | `BREEZE` present | `breeze run pytest <path>` |
+
+You can also call `python scripts/ci/prek/breeze_context.py` to auto-detect and
+print `host` or `breeze`.
+
+Commands
+--------
+
+On the Host
+-----------
+
+`<PROJECT>` is the folder containing the relevant `pyproject.toml`, e.g.
+`airflow-core`, `providers/amazon`, `task-sdk`, `scripts`.
+
+```bash
+# Run a single test method
+uv run --project <PROJECT> pytest path/to/test.py::TestClass::test_method -xvs
+
+# Run all tests in a file
+uv run --project <PROJECT> pytest path/to/test.py -xvs
+
+# Run all tests in a package
+uv run --project <PROJECT> pytest path/to/package/ -xvs
+
+# If uv fails due to missing system dependencies, fall back to Breeze:
+breeze testing core-tests --run-in-parallel
+```
+
+Inside Breeze
+-------------
+
+```bash
+# Run a single test method
+breeze run pytest path/to/test.py::TestClass::test_method -xvs
+
+# Run all tests in a file
+breeze run pytest path/to/test.py -xvs
+
+# Run Breeze's built-in parallel test runners
+breeze testing core-tests --run-in-parallel
+breeze testing providers-tests --run-in-parallel
+```
+
+Workflow Context
+----------------
+
+This is **Scenario 2** of the standard Airflow contributor workflow:
+
+1. stage-changes
+2. run-static-checks
+3. → **run-unit-tests** (this skill)
+
+Run static checks first to avoid failing tests due to trivial formatting issues.
+
+Prerequisites
+-------------
+
+- **Host:** `uv` must be installed and the project synced.
+- **Breeze:** Docker must be running and the Breeze image built. In case breeze image needs rebuilding, it should be rebuilt (answer yes to the question of rebuilding).
+- Tests requiring a database backend: use `--backend postgres` or `--backend mysql`.
+
+Interpreting Results
+--------------------
+
+| Exit Code | Meaning |
+|---|---|
+| 0 | All selected tests passed |
+| 1 | One or more tests failed — check `FAILED` lines in output |
+
+Use `-xvs` flags for verbose output and early exit on first failure. This makes
+it easier to read the root cause when tests fail.
+
+Success Criteria
+----------------
+
+`pytest` exits with code 0 and reports `passed` for all selected tests with no
+`FAILED` or `ERROR` lines.

.agents/skills/stage-changes/SKILL.md

@@ -0,0 +1,68 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+      https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- markdownlint-disable MD022 -->
+---
+name: stage-changes
+description: Stage changed files for commit using git add. This is a host-only operation — it must never run inside a Breeze container.
+---
+<!-- markdownlint-enable MD022 -->
+
+Stage Changes
+=============
+
+Stage specific files or directories before running static checks or committing.
+
+Source of truth for contribution workflow order is `contributing-docs`; this skill
+enforces the host/container guardrails when applying that workflow.
+
+Host-Only Guardrail
+-------------------
+
+This skill operates on the **host** working tree. Running `git` commands inside a
+Breeze container will silently operate on container-local paths that differ from your
+actual working tree.
+
+**Before running:** Confirm you are on the host by checking that the `BREEZE`
+environment variable is **not** set. If it is set, you are inside Breeze — exit
+first (`exit` or `Ctrl-D`), then stage changes.
+
+Commands
+--------
+
+```bash
+# Stage a single file
+git add path/to/file.py
+
+# Stage multiple files
+git add path/to/file1.py path/to/file2.py
+
+# Stage all changes in a directory
+git add providers/amazon/
+
+# Stage all tracked changes
+git add -u
+```
+
+Workflow Context
+----------------
+
+This is **Scenario 1, Step 1** of the standard Airflow contributor workflow:
+
+1. → **stage-changes** (this skill)
+2. run-static-checks
+3. run-unit-tests
+
+Always stage changes *before* running `prek` (pre-commit) so the hooks operate on
+the correct set of files.
+
+Prerequisites
+-------------
+
+- You must be on the **host** (not inside Breeze). See guardrail above.
+- Files must already exist and be tracked by git (or explicitly added with `git add`).
+
+Success Criteria
+----------------
+
+`git status` shows staged changes under "Changes to be committed".

.pre-commit-config.yaml

@@ -449,6 +449,13 @@ repos:
     # changes quickly - especially when we want the early modifications from the first local group
     # to be applied before the non-local prek hooks are run
     hooks:
+      - id: validate-agent-skills
+        name: Validate Agent Skills structure
+        entry: ./scripts/ci/prek/validate_skills.py
+        language: python
+        pass_filenames: false
+        additional_dependencies: ['pyyaml>=6.0.3']
+        files: ^\.agents/skills/.*$
       - id: check-shared-distributions-structure
         name: Check shared distributions structure
         entry: ./scripts/ci/prek/check_shared_distributions_structure.py