Pranaykarvi commented on issue #62500:
URL: https://github.com/apache/airflow/issues/62500#issuecomment-4045802862
@jason810496 @potiuk, building on the discussion so far, I want to
directly address the open question on the transformation mechanism.
The core tension in this thread is between two risks:
- Parsing docs (HARDIK/Abhishek approach): brittle when formatting
changes, as haseebmalik pointed out
- Manual maintenance (haseebmalik approach): reliable but depends on
human discipline, which is exactly what we're trying to reduce
I'd propose a middle path: **contributor-docs-as-spec with
schema-validated structured blocks**.
Instead of parsing free-form RST or maintaining a separate YAML, we
introduce lightweight fenced blocks directly inside the contributing
docs — similar to how doctest works in Python:
```workflow
id: run-tests
local: uv run --project {distribution_folder} pytest {test_path}
fallback: breeze exec pytest {test_path} -xvs
fallback_condition: missing_system_deps
```
These blocks are:
- Human-readable inline with the contributing guide
- Machine-parseable with a strict schema (no fragile RST parsing)
- The generator extracts ONLY these blocks — the surrounding prose
stays untouched for humans
- A prek hook validates that every block compiles to a valid skill
definition and fails CI on drift
This directly addresses the long-term maintainability concern because:
1. Contributor edits docs → must update the structured block in the
same place → single atomic commit
2. prek fails if block schema is invalid
3. No separate YAML file to fall out of sync
4. No fragile full-doc parsing
The agent skill definitions are then generated from these blocks and
committed — prek fails if the generated output diverges.
Happy to prototype this approach if it aligns with the direction
you're thinking.
GitHub: github.com/Pranaykarvi
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
