Hi Yeonguk, Jarek,
> It might be helpful if we could define a recommended structure or
guidance for how each locale-specific skill should document:
>From my perspective, there are two cases: 1) the global-level SKILL.md, and
2) a sub-skill file for each locale.
For case 1), I think we definitely need to reach consensus at the project
maintainer level about what the structure should look like, and Kevin
Yang’s draft [1] LGTM overall and is close to being merged.
For case 2), I would prefer to defer the rules and guidelines to the locale
maintainers instead of defining a strict structure for what the locale
sub-skill should look like. Since not all locales have dedicated members
who can help define or brainstorm the exact translation rules, I think that
as long as the locale maintainers have reached consensus on their
sub-skill, it should be fine, because it is still up to the locale
maintainers to decide whether the generated translations make sense or not.
Locale maintainers can definitely use other locales as references, and even
look at different OSS projects (FastAPI might be a good candidate) when
defining their skills.
If there is really any convention for each locale sub-skill, I would
suggest focusing only on the rules and not including the “Terminology
decision” or “Rationale (WHY)” sections, to avoid adding more noise to the
agent context window. Those details are indeed important, but
`airflow-core/src/airflow/ui/public/i18n/locales/{locale}/README.md` would
be a better place to track those discussions IMHO.
> In short, it's about Licence headers in such markdown files that are
intended to be consumed by agents - the current source header is far too
much comparing to the usual size of such skills (our AGENTS.md has 37% of
token overhead **just** for the licence text). It adds a lot of overhead -
and we should shorten it.
I completely agree with this! This is also why I would prefer **not** to
include past discussions in the skill itself, so that we can keep the
context as short as possible.
Thanks everyone for joining the discussion and sharing your thoughts!
[1] https://github.com/apache/airflow/pull/62059
Best,
Jason
On Tue, Feb 17, 2026 at 8:32 PM Jarek Potiuk <[email protected]> wrote:
> PR shortening licences and excluding the relevant files from our "source"
> releases https://github.com/apache/airflow/pull/62073
>
> On Tue, Feb 17, 2026 at 12:07 PM Jarek Potiuk <[email protected]> wrote:
>
> > Also - I would like to draw attention to a related discussion that
> @Dev-il
> > (Ilya) started first on slack and then we moved it to legal-discuss in
> > https://lists.apache.org/thread/j1tn63r2lf13v3d1tnnqff8fkcl4nx53 of the
> > ASF. I am heavily participating in it.
> > In short, it's about Licence headers in such markdown files that are
> > intended to be consumed by agents - the current source header is far too
> > much comparing to the usual size of such skills (our AGENTS.md has 37% of
> > token overhead **just** for the licence text). It adds a lot of overhead
> -
> > and we should shorten it.
> >
> > While we wait for an official clarification on whether we could do it
> > officially as Ilya proposed (I think we can and I will talk to my friend
> -
> > VP legal, Roman to fast-track his response on that) - we can definitely
> do
> > it now ourselves. We can do it especially if we make sure we disable such
> > files from the source tarballs we produce as official releases (we can
> > easily do it). I will make a PR shortly to do it now without waiting for
> > official FAQ/clarifications in the name of "better ask for forgiveness
> than
> > permission".
> >
> > J.
> >
> >
> > On Tue, Feb 17, 2026 at 11:58 AM Jarek Potiuk <[email protected]> wrote:
> >
> >> Good ideas indeed. I am personally going to dive deeper into making good
> >> agentic descriptions of skills and the like, and while initially I was a
> >> bit sceptical, thinking that "it's enough for the agent to look it up",
> I
> >> had a few cases in recent translation in Polish that would benefit from
> >> describing some of the whys (for example we agreed on - a bit
> controversial
> >> but fun - "Cyngiel" translation for Triggerer in Polish - and both my
> >> agent and myself missed it in the last round of translations.
> Documenting
> >> such decisions and adding more targeted and constraint guidelines for
> the
> >> agents is definitely going to improve the quality of those
> translations. We
> >> can even treat it as an interesting exercise to describe the rules and
> >> create "language skills" - between the translators, and eventually
> RERUN
> >> the agent on all our translations to apply the skills to translations
> >> already made. It would be an interesting exercise to see if the
> >> translations will get better.
> >>
> >> I am 100% in for Polish SKILL development :) - I also saw that there
> were
> >> other Polish contributors - new - signing up for those, so we can also
> make
> >> it a nice small collaborative effort to work out a good skill for that.
> >>
> >> J.
> >>
> >>
> >> On Tue, Feb 17, 2026 at 7:03 AM Yeonguk Choo <[email protected]>
> >> wrote:
> >>
> >>> Hi, Jason,
> >>>
> >>> I think this is a great step forward for improving translation
> >>> consistency
> >>> in Airflow,
> >>> and I’m personally excited to see Agent Skills being introduced to the
> >>> repository for the first time 🙌
> >>>
> >>> I have a similar concern to what Jens mentioned.
> >>>
> >>> For Korean, we still have some open discussions within the translation
> >>> team.
> >>> There are cases where directly translating certain Airflow terms into
> >>> Korean sounds very unnatural, so we sometimes use transliterations
> >>> instead.
> >>> On the other hand, some terms are translated more literally.
> >>>
> >>> However, we have not yet fully aligned on the WHY behind those
> decisions,
> >>> and opinions may differ depending on the user perspective.
> >>>
> >>> Unlike the German case, we do not yet have clearly established
> >>> terminology
> >>> principles documented.
> >>> Because of that, I am not entirely confident about what criteria we
> >>> should
> >>> use when reviewing PRs for the Korean skill definition.
> >>>
> >>> It might be helpful if we could define a recommended structure or
> >>> guidance
> >>> for how each locale-specific skill should document:
> >>>
> >>> * Terminology decision
> >>> * Rationale (WHY)
> >>> * Preferred patterns (e.g., transliteration vs. literal translation)
> >>> * Cases that are intentionally flexible
> >>>
> >>> I think having a shared guidance framework across locales would make
> >>> reviews more consistent and reduce ambiguity.
> >>>
> >>> Curious to hear others’ thoughts.
> >>>
> >>> Best,
> >>> Yeonguk
> >>>
> >>> 2026년 2월 17일 (화) PM 12:25, Zhe-You Liu <[email protected]>님이 작성:
> >>>
> >>> > Hi Jens,
> >>> >
> >>> > Great point! I agree that each locale should track the reasons for
> its
> >>> > terminology choices. I will cross-post this to the German sub-issue
> and
> >>> > mention this convention in the meta issue. Thanks!
> >>> >
> >>> > Best,
> >>> > Jason
> >>> >
> >>> > On Tue, Feb 17, 2026 at 5:34 AM Jens Scheffler <[email protected]>
> >>> > wrote:
> >>> >
> >>> > > Hi!
> >>> > >
> >>> > > Good initiative to make it common. Please consider that for the
> >>> German
> >>> > > we created a
> >>> > > airflow-core/src/airflow/ui/public/i18n/locales/de/README.md that
> >>> > > describes _WHY_ we have selected which specific terms in the local
> >>> > > translation. So encouraging that other translations maybe follow
> same
> >>> > > approach. If need to be re-formatted for agent based processing
> this
> >>> > > would be finde but I'd otherwise request to consider the existing
> >>> > > definitions.
> >>> > >
> >>> > > Not sure if it is beneficial if it is renamed "de.md" instead of
> >>> > > README.md though.
> >>> > >
> >>> > > Jens
> >>> > >
> >>> > > On 16.02.26 15:57, Shahar Epstein wrote:
> >>> > > > Great initiative Jason!
> >>> > > >
> >>> > > >
> >>> > > > Shahar
> >>> > > >
> >>> > > > On Mon, Feb 16, 2026, 15:58 Zhe-You(Jason) Liu <
> >>> [email protected]>
> >>> > > wrote:
> >>> > > >
> >>> > > >> Hi everyone,
> >>> > > >>
> >>> > > >> I would like to invite new contributors looking for a "Good
> First
> >>> > Issue"
> >>> > > >> (everyone else is welcome too!) to help define the **Translation
> >>> Agent
> >>> > > >> Skills for Airflow Terminology** [1].
> >>> > > >>
> >>> > > >> We are looking to define **21 Translation Agent skills** in
> total.
> >>> > This
> >>> > > >> includes **1 global-level skill** and **20 locale-specific
> >>> skills**.
> >>> > > >>
> >>> > > >> The goal is to implement a generic, up-to-date, and
> >>> low-maintenance
> >>> > > >> solution using Open-standardized Agent Skills [2]. This will
> help
> >>> the
> >>> > > >> Airflow community maintain translations more efficiently,
> ensuring
> >>> > > better
> >>> > > >> consistency across locales and reducing hallucinations in
> >>> AI-assisted
> >>> > > >> workflows.
> >>> > > >>
> >>> > > >> The skills will be organized as follows:
> >>> > > >> ```
> >>> > > >> .github/skills/airflow-translations
> >>> > > >> ├── locales
> >>> > > >> │ ├── ar.md
> >>> > > >> │ # ... all current locales, each with locale-specific skills
> >>> > > >> │ └── zh-TW.md
> >>> > > >> └── SKILL.md # Global-level Airflow terminology guidelines
> >>> > > >> ```
> >>> > > >>
> >>> > > >> - **`SKILL.md`**: Contains only global-level Airflow terminology
> >>> > > >> guidelines.
> >>> > > >> - **`locales/{locale-name}.md`**: Documents guidelines specific
> to
> >>> > that
> >>> > > >> language, based on the existing locale files found in
> >>> > > >>
> `airflow-core/src/airflow/ui/public/i18n/locales/{locale-name}/`.
> >>> > > >> - **Inheritance**: All `locales/{locale-name}.md` files will
> >>> depend on
> >>> > > the
> >>> > > >> global-level `SKILL.md` first.
> >>> > > >>
> >>> > > >> This is a significant milestone: these will be the **first Agent
> >>> > Skills
> >>> > > >> defined in the Airflow repository**. I am looking forward to
> >>> seeing
> >>> > how
> >>> > > we
> >>> > > >> can leverage these skills to make our AI-assisted tools more
> >>> accurate
> >>> > > and
> >>> > > >> consistent for our contribution processes.
> >>> > > >>
> >>> > > >> **How to contribute:**
> >>> > > >> If you are interested, please **comment on the specific
> sub-issue
> >>> you
> >>> > > want
> >>> > > >> to work on** (rather than the meta issue), and I will assign it
> to
> >>> > you.
> >>> > > >>
> >>> > > >> Thank you in advance for your contribution!
> >>> > > >>
> >>> > > >> [1] https://github.com/apache/airflow/issues/61984
> >>> > > >> [2] https://agentskills.io/home
> >>> > > >>
> >>> > > >> Best regards,
> >>> > > >> Jason
> >>> > > >>
> >>> > >
> >>> > >
> ---------------------------------------------------------------------
> >>> > > To unsubscribe, e-mail: [email protected]
> >>> > > For additional commands, e-mail: [email protected]
> >>> > >
> >>> > >
> >>> >
> >>>
> >>
>
