feat(labels): capability taxonomy + validator enforcement + sync check

.claude/skills/contributor-nomination/SKILL.md

@@ -17,6 +17,7 @@ when_to_use: |
   provided and the user has not indicated they want to assess
   a contributor.
 argument-hint: "<github-handle> [window:Nm] [target:committer|pmc]"
+capability: capability:stats
 license: Apache-2.0
 ---
 

.claude/skills/issue-fix-workflow/SKILL.md

@@ -16,6 +16,7 @@ when_to_use: |
   to `issue-triage` for issues classified BUG or
   FEATURE-REQUEST. Skip when the fix is non-trivial enough to
   need design discussion — those go through an RFC first.
+capability: capability:fix
 license: Apache-2.0
 ---
 

.claude/skills/issue-reassess-stats/SKILL.md

@@ -13,6 +13,7 @@ when_to_use: |
   "which issues still fail across pool runs". Also as a
   pre-release check on whether the EOL pool has dropped, and
   as a periodic health-of-the-backlog view.
+capability: capability:stats
 license: Apache-2.0
 ---
 

.claude/skills/issue-reassess/SKILL.md

@@ -17,6 +17,7 @@ when_to_use: |
   audit before releases or after a major version cut. Skip
   when the goal is per-PR triage — that is `pr-management-triage`
   — or when the issues are still in active triage flow.
+capability: capability:reassess
 license: Apache-2.0
 ---
 

.claude/skills/issue-reproducer/SKILL.md

@@ -16,6 +16,7 @@ when_to_use: |
   issue in its candidate set. Skip when the issue does not
   carry runnable example code — use `issue-triage` to assess
   instead.
+capability: capability:reassess
 license: Apache-2.0
 ---
 

.claude/skills/issue-triage/SKILL.md

@@ -16,6 +16,7 @@ when_to_use: |
   Skip when team consensus has landed — invoke
   `/issue-fix-workflow` for confirmed bugs or the appropriate
   closure flow directly.
+capability: capability:triage
 license: Apache-2.0
 ---
 

.claude/skills/list-steward-skills/SKILL.md

@@ -15,6 +15,7 @@ when_to_use: |
   repository — agents route via the live frontmatter
   `description` field directly and do not need this index to
   choose a skill.
+capability: capability:stats
 license: Apache-2.0
 ---
 

.claude/skills/pairing-self-review/SKILL.md

@@ -15,6 +15,7 @@ when_to_use: |
   whether their branch is ready before requesting a human maintainer review.
   Skip when a PR is already open — use `pr-management-code-review` for that.
 argument-hint: "[base:<ref>] [staged] [path:<glob>]"
+capability: capability:review
 license: Apache-2.0
 ---
 <!-- SPDX-License-Identifier: Apache-2.0

.claude/skills/pr-management-code-review/SKILL.md

@@ -13,6 +13,7 @@ when_to_use: |
   ready-for-maintainer-review queue". Use after `pr-management-triage` has produced reviewable PRs; skip when triage
   has not yet engaged the PR.
 argument-hint: "[pr:N] [area:LBL] [collab:true|false] [team:NAME] [ready] [dry-run]"
+capability: capability:review
 license: Apache-2.0
 ---
 <!-- SPDX-License-Identifier: Apache-2.0

.claude/skills/pr-management-mentor/SKILL.md

@@ -21,6 +21,7 @@ when_to_use: |
   thread is security-sensitive, or when the maintainer has
   *deliberately* not replied yet — ask before invoking.
 argument-hint: "[issue-or-pr-number]"
+capability: capability:review
 license: Apache-2.0
 ---
 <!-- SPDX-License-Identifier: Apache-2.0

.claude/skills/pr-management-stats/SKILL.md

@@ -12,6 +12,7 @@ when_to_use: |
   health check, before or after a triage sweep, or as an input to a planning
   session.
 argument-hint: "[repo:owner/name] [since:date] [clear-cache]"
+capability: capability:stats
 license: Apache-2.0
 ---
 

.claude/skills/pr-management-triage/SKILL.md

@@ -20,6 +20,7 @@ when_to_use: |
   skill is a no-op when every candidate is already triaged or
   inside its grace window.
 argument-hint: "[pr:N] [label:LBL] [author:LOGIN] [review-for-me] [stale] [repo:owner/name]"
+capability: capability:triage
 license: Apache-2.0
 ---
 <!-- SPDX-License-Identifier: Apache-2.0

.claude/skills/security-cve-allocate/SKILL.md

@@ -17,6 +17,7 @@ when_to_use: |
   valid/invalid decision has landed, or for trackers that
   already carry a CVE ID in their *CVE tool link* body field.
 argument-hint: "[issue-number] [CVE-YYYY-NNNNN]"
+capability: capability:resolve
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-deduplicate/SKILL.md

@@ -16,6 +16,7 @@ when_to_use: |
   appropriate as a periodic cleanup action when a triager spots two
   open trackers describing the same bug from different angles.
 argument-hint: "[kept-issue] [duplicate-issue]"
+capability: capability:resolve
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-fix/SKILL.md

@@ -20,6 +20,9 @@ when_to_use: |
   classified as valid vulnerabilities, or changes that require
   the private-PR fallback path.
 argument-hint: "[issue-number]"
+capability:
+  - capability:fix
+  - capability:resolve
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-import-from-md/SKILL.md

@@ -18,6 +18,7 @@ when_to_use: |
   (`security-issue-import`) or when there is a public PR to
   anchor the import on (`security-issue-import-from-pr`).
 argument-hint: "[path-to-markdown-file]"
+capability: capability:intake
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-import-from-pr/SKILL.md

@@ -20,6 +20,7 @@ when_to_use: |
   does not host a validity discussion. For reports that arrive on
   `<security-list>`, use `security-issue-import`.
 argument-hint: "[pr-number] [repo:owner/name]"
+capability: capability:intake
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-import/SKILL.md

@@ -21,6 +21,7 @@ when_to_use: |
   answered-and-closed on-thread. Use `import last 30d` / `import all`
   (= 90d) for a wider backlog sweep when genuinely warranted.
 argument-hint: "[import] [last Nd|all] [skip threadId]"
+capability: capability:intake
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-invalidate/SKILL.md

@@ -21,6 +21,7 @@ when_to_use: |
   already shipped — closing as invalid then is a retraction with
   public consequences and warrants explicit team escalation.
 argument-hint: "[issue-number]"
+capability: capability:resolve
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-sync/SKILL.md

@@ -16,6 +16,7 @@ when_to_use: |
   where the team member wants to reconcile a batch of open issues with the
   current state of the world.
 argument-hint: "[issue-number]"
+capability: capability:intake
 license: Apache-2.0
 ---
 

.claude/skills/security-issue-triage/SKILL.md

@@ -23,6 +23,7 @@ when_to_use: |
   `/security-cve-allocate` (VALID),
   `/security-issue-invalidate` (INFO-ONLY / INVALID), or
   `/security-issue-deduplicate` (PROBABLE-DUP) directly.
+capability: capability:triage
 license: Apache-2.0
 ---
 

.claude/skills/security-tracker-stats-dashboard/SKILL.md

@@ -7,6 +7,7 @@ when_to_use: |
   variations. Also when an existing dashboard at the configured output
   path is stale (older than ~24 h) and the user is reviewing tracker
   health. Read-only — the skill never modifies any tracker state.
+capability: capability:stats
 license: Apache-2.0
 ---
 

.claude/skills/setup-isolated-setup-doctor/SKILL.md

@@ -18,6 +18,9 @@ when_to_use: |
   permission errors). Also a good periodic check after every
   Claude Code upgrade — the sandbox profile evolves and a
   previously-working call may have moved into deny.
+capability:
+  - capability:setup
+  - capability:reassess
 license: Apache-2.0
 ---
 

.claude/skills/setup-isolated-setup-install/SKILL.md

@@ -17,6 +17,7 @@ when_to_use: |
   already in place — use `setup-isolated-setup-verify` (to
   confirm completeness) or `setup-isolated-setup-update` (to
   refresh against the framework's latest) instead.
+capability: capability:setup
 license: Apache-2.0
 ---
 

.claude/skills/setup-isolated-setup-update/SKILL.md

@@ -14,6 +14,7 @@ when_to_use: |
   blocked Bash call now appears to succeed. Recommended cadence
   per the doc: once per Claude Code upgrade or once a month,
   whichever comes first. Cheap to re-run; never destructive.
+capability: capability:setup
 license: Apache-2.0
 ---
 

.claude/skills/setup-isolated-setup-verify/SKILL.md

@@ -17,6 +17,7 @@ when_to_use: |
   time a previously-blocked Bash call appears to have succeeded
   (the "did a denial silently turn into an allow?" canary). Cheap
   to re-run; never destructive.
+capability: capability:setup
 license: Apache-2.0
 ---
 

.claude/skills/setup-override-upstream/SKILL.md

@@ -15,6 +15,7 @@ when_to_use: |
   override locally for a while and deciding the change is
   worth contributing back.
 argument-hint: "[skill-name]"
+capability: capability:setup
 license: Apache-2.0
 ---
 
@@ -276,11 +277,29 @@ In `<framework-clone>`:
 3. **Confirm with the user before posting**. Show the
    exact title + body. Wait for "OK to post" / "yes" /
    "send" / similar before running `gh pr create`.
-4. Write the PR body to a tempfile first, then create the PR:
+4. **Pick the labels.** Every framework PR carries at least one
+   `area:*` and one `capability:*` label per
+   [`docs/labels-and-capabilities.md`](../../../docs/labels-and-capabilities.md).
+   The override is upstreaming a change to skill `<skill>`, so:
+   - `area:*` — follow the skill's family
+     (`area:pr-management` for `pr-management-*`, `area:security`
+     for `security-*`, `area:setup` for `setup-*`, `area:issue`
+     for `issue-*`, etc.).
+   - `capability:*` — the capability the change is *implementing*,
+     not the file paths touched. Look up the skill's capability in
+     the skill-to-capability map at
+     [`docs/labels-and-capabilities.md#capability-to-skill-map`](../../../docs/labels-and-capabilities.md#capability-to-skill-map).
+   - Add `kind:*` and `mode:*` when they apply per the same doc.
+
+   Surface the chosen labels in the confirmation preview alongside
+   the PR title and body, so the user sees them before posting.
+
+5. Write the PR body to a tempfile first, then create the PR:
    ```bash
    # Write tool: file_path: /tmp/override-pr-body.md, content: <PR body>
    gh pr create --repo apache/airflow-steward --base main \
-     --head <user>:<branch> --title "..." --body-file /tmp/override-pr-body.md
+     --head <user>:<branch> --title "..." --body-file /tmp/override-pr-body.md \
+     --label "area:<area>" --label "capability:<capability>"
    ```
 
 ### Step 7 — Post-PR cleanup pointer

.claude/skills/setup-shared-config-sync/SKILL.md

@@ -18,6 +18,9 @@ when_to_use: |
   `setup-isolated-setup-update` surfaces drift on a script the
   user keeps in `~/.claude-config/` and wants propagated to
   other machines.
+capability:
+  - capability:intake
+  - capability:setup
 license: Apache-2.0
 ---
 

.claude/skills/setup-steward/SKILL.md

@@ -30,6 +30,7 @@ when_to_use: |
   maintenance: "upgrade steward", "verify steward setup",
   "check steward drift", "the snapshot is stale".
 argument-hint: "[adopt|upgrade|worktree-init|verify|override skill-name|unadopt]"
+capability: capability:setup
 license: Apache-2.0
 ---
 

.claude/skills/write-skill/SKILL.md

@@ -6,14 +6,15 @@ description: |
   shape (frontmatter, resources, placeholder convention,
   prompt-injection defences, Privacy-LLM gate-check) and
   validates via the framework's existing
-  [`tools/skill-validator`](../../../tools/skill-validator/).
+  [`tools/skill-and-tool-validator`](../../../tools/skill-and-tool-validator/).
   Scaffolds new skills via `init_skill.py`.
 when_to_use: |
   Invoke when the user says "write a skill", "create a new skill",
   "add a skill for X", "I want to make a skill that does Y", or
   variations thereof. Also when refactoring or expanding an
   existing skill that should pick up the framework's current
   conventions (e.g. the prompt-injection-defence patterns).
+capability: capability:setup
 license: Apache-2.0
 ---
 
@@ -67,7 +68,7 @@ will recognise the workflow shape:
   [`docs/setup/install-recipes.md`](../../../docs/setup/install-recipes.md),
   not as zip artefacts. The upstream's `package_skill.py` is not
   included; **validation** is performed by the existing
-  [`tools/skill-validator`](../../../tools/skill-validator/),
+  [`tools/skill-and-tool-validator`](../../../tools/skill-and-tool-validator/),
   which is the framework's superset of the upstream's
   `quick_validate.py`.
 - **New Step 5 (security checklist)** added — a hard
@@ -108,6 +109,12 @@ skill bundles:
 │   │   ├── name (required, kebab-case, must equal directory name)
 │   │   ├── description (required, third-person)
 │   │   ├── when_to_use (required, third-person trigger phrases)
+│   │   ├── capability (required, one OR a YAML list of values from:
+│   │   │   `capability:triage`, `capability:review`, `capability:fix`,
+│   │   │   `capability:intake`, `capability:reconciliation`,
+│   │   │   `capability:resolve`, `capability:reassess`,
+│   │   │   `capability:stats`, `capability:setup` — see
+│   │   │   [`docs/labels-and-capabilities.md`](../../../docs/labels-and-capabilities.md))
 │   │   └── license: Apache-2.0 (required, exact string)
 │   ├── SPDX header comment + placeholder-convention comment
 │   ├── # <skill-name> heading
@@ -301,7 +308,7 @@ no external content / no private content).
 Run the framework's existing skill validator:
 
 ```bash
-uv run --directory tools/skill-validator skill-validator \
+uv run --directory tools/skill-and-tool-validator skill-and-tool-validator \
   .claude/skills/<skill-name>/SKILL.md
 ```
 
@@ -359,6 +366,21 @@ for the override → upstream loop.
   expansion at the wrong layer.
 - **Always set `license: Apache-2.0` in the frontmatter.** The
   validator enforces this; the prek run will fail otherwise.
+- **Always declare a `capability:`** in the frontmatter, picking
+  one or more buckets from
+  [`docs/labels-and-capabilities.md`](../../../docs/labels-and-capabilities.md).
+  Most skills fit a single bucket; when a skill genuinely spans
+  lifecycle phases (e.g. `security-issue-fix` does
+  `capability:fix` + `capability:resolve`,
+  `setup-isolated-setup-doctor` does
+  `capability:setup` + `capability:reassess`), use the YAML list
+  form and list **all** that apply — do not collapse to one to be
+  neat. If the skill doesn't fit any of the nine buckets at all,
+  treat that as a design signal worth pausing for — either the
+  bucket set needs a new entry (raise an issue against
+  [`docs/labels-and-capabilities.md`](../../../docs/labels-and-capabilities.md))
+  or the skill's scope is straddling too many phases and should be
+  split. Do not invent ad-hoc capability values.
 - **Always credit upstream content in `NOTICE`.** When adapting
   third-party skills (as this skill itself was adapted from
   `JuliusBrussee/awesome-claude-skills`), the project root
@@ -376,12 +398,17 @@ for the override → upstream loop.
 - [`AGENTS.md`](../../../AGENTS.md) — the framework's authoring
   conventions, placeholder convention, prompt-injection
   absolute rule.
+- [`docs/labels-and-capabilities.md`](../../../docs/labels-and-capabilities.md)
+  — the label taxonomy: `area:*` + `capability:*` dimensions, the
+  nine capability buckets, the skill / tool → capability map, and
+  the rule that every framework issue / PR / tool / skill / doc
+  declares its capability.
 - [`docs/setup/agentic-overrides.md`](../../../docs/setup/agentic-overrides.md)
   — the `Adopter overrides` contract every skill consults.
 - [`docs/setup/install-recipes.md`](../../../docs/setup/install-recipes.md)
   — the snapshot model that distributes skills (no zip
   packaging — Step 5 of the upstream's flow is dropped).
-- [`tools/skill-validator/`](../../../tools/skill-validator/) —
+- [`tools/skill-and-tool-validator/`](../../../tools/skill-and-tool-validator/) —
   the framework's frontmatter / placeholder / link validator.
 - [`tools/privacy-llm/wiring.md`](../../../tools/privacy-llm/wiring.md)
   — the Privacy-LLM gate-check boilerplate Step 5 references.

.claude/skills/write-skill/scripts/init_skill.py

@@ -49,7 +49,7 @@
   skill reads private content.
 
 The skill is *not* validated by this script. Run
-``tools/skill-validator/`` separately after editing.
+``tools/skill-and-tool-validator/`` separately after editing.
 """
 
 from __future__ import annotations

.claude/skills/write-skill/security-checklist.md

@@ -231,7 +231,7 @@ backstops:
 1. **`init_skill.py`** scaffolds a SKILL.md skeleton with
    placeholders for the injection-guard callout (Pattern 4) and
    the Privacy-LLM gate-check (Pattern 6).
-2. **`tools/skill-validator`** validates frontmatter shape and
+2. **`tools/skill-and-tool-validator`** validates frontmatter shape and
    placeholder usage — it does not check for the patterns above.
 3. **`prek` hooks** (`check-placeholders`, `markdownlint`,
    `typos`) catch common mistakes but not pattern violations.

.github/dependabot.yml

@@ -132,7 +132,7 @@ updates:
           - "*"
 
   - package-ecosystem: "uv"
-    directory: "/tools/skill-validator"
+    directory: "/tools/skill-and-tool-validator"
     schedule:
       interval: "weekly"
     cooldown:
@@ -141,7 +141,7 @@ updates:
       semver-minor-days: 7
       semver-patch-days: 7
     groups:
-      skill-validator-deps:
+      skill-and-tool-validator-deps:
         patterns:
           - "*"