Table of Contents generated with DocToc

• Labels and capabilities
  • Label dimensions
    • 1. area:* — subject
    • 2. capability:* — what the tool does
    • 3. kind:* — change type (pre-existing)
    • 4. mode:* — handling mode (pre-existing)
    • Standalone labels
  • Capability to skill map
  • Capability to tool map
  • The rule
    • A GitHub issue
    • A pull request
    • A new tool under tools/
    • A new skill under .claude/skills/
    • A new doc under docs/
  • Why this exists

Labels and capabilities

This page is the canonical reference for the label taxonomy used on issues and pull requests in this framework repository (apache/airflow-steward). It also defines the capability model that classifies what each skill or tool in the framework actually does, independent of which subject area it sits under.

Every issue and pull request opened against this repository should carry at least one area:* label and at least one capability:* label. New tools and new skills must declare their capability up front (see The rule).

Scope caveat. This taxonomy applies to this framework repository. Skills that create issues or PRs on an adopter’s tracker (e.g. security-issue-import, security-issue-fix, issue-fix-workflow) use the adopter’s own label scheme — adopters are free to mirror this taxonomy in their own repo but are not required to.

Label dimensions

The repository’s labels fall into four orthogonal dimensions. An issue or PR typically carries one label from each dimension that applies.

1. area:* — subject

What part of the framework does this touch?

2. capability:* — what the tool does

Nine buckets. A tool or skill carries one or more capability:* labels. Most map cleanly to a single bucket; dual-capability cases are real and explicitly enumerated below. Issues and PRs follow the same rule — apply every capability the change is implementing.

When a skill or tool spans multiple capabilities, list all of them in its frontmatter / README. Do not pick a single “primary” to be neat; that loses information the label system exists to surface.

The capability:* dimension is orthogonal to area:*. A single query can answer “how is our triage stack doing across PR + issue + security?” by filtering on capability:triage alone, without enumerating per-area queries.

3. kind:* — change type (pre-existing)

4. mode:* — handling mode (pre-existing)

Standalone labels

marketing (branding artefacts), dependencies (dependency-update PRs), python:uv (Python uv-managed code), plus the default GitHub labels (bug, enhancement, documentation, good first issue, etc.).

Capability to skill map

Capabilities for every skill currently in .claude/skills/. Skills with two values (separated by +) carry both labels.

Capability to tool map

Tools under tools/. Tools with two values (separated by +) carry both labels — the dual role is explained in each row.

A tool’s capabilities are determined by its use-case lifecycle phases, not by which skills happen to consume it. tools/github is called by every triage / intake / fix / resolve skill but is tagged only capability:setup because it doesn’t encode any one lifecycle phase — it is pure substrate. tools/cve-org, by contrast, exists specifically to do CVE publication and to record that result; both the resolve action and the intake of state into the tracker are first-class jobs of the tool, so it carries both labels.

When a tool grows to serve a new lifecycle phase as a first-class feature (rather than as generic substrate that other skills happen to compose), add the new capability:* label to its README and to the table above.

The rule

When you create any of the following on this repository, declare the capability:

A GitHub issue

Apply at least one area:* AND one capability:* label. If the issue genuinely spans capabilities, apply both — for example, #337 carries both capability:reconciliation and capability:setup because it covers a new substrate tool and a new sync-flow integration.

A pull request

Same: area:* AND capability:*. Match the capability the change is implementing, not the file paths it happens to touch. A PR that adjusts the validator config to support a new triage rule is capability:triage (the change’s purpose), not capability:setup (the file it edited).

A new tool under tools/

Declare the tool’s capability in the first paragraph of its README using the line:

**Capability:** capability:NAME

If the tool serves more than one capability, list both. Substrate bridges (tools/github, tools/gmail, …) default to capability:setup unless they encode a specific lifecycle capability.

A new skill under .claude/skills/

Declare the capability in the skill’s frontmatter:

---
name: my-new-skill
description: |
  ...
capability: capability:NAME
---

The write-skill skill prompts for this on every new-skill scaffold.

A new doc under docs/

Capability-specific docs (e.g. a guide for a single skill family) should link to this page and name the capability in their first paragraph. Cross-cutting docs (MISSION.md, top-level READMEs) need no capability marker.

Why this exists

The original area:* labels split issues by subject — useful for “what part of the codebase is this?” but unable to answer “what kind of thing is this?”. The capability:* dimension fills that gap and is orthogonal: a triage-rule change in PR management (area:pr-management + capability:triage) and a triage-rule change in security (area:security + capability:triage) become trivially findable as a cohort even though they live in different families.

Capability is also a forcing function for skill design: if a new skill doesn’t fit any of the nine buckets cleanly, that’s a signal worth inspecting before the skill ships.