How-to: add a sub_area to the capability graph

CAPABILITY-GRAPH.yaml is the source of truth for sub-areas. Declare it here before any curated skill references it — the semantic audit fails otherwise.

Steps

1. Open docs/reference/registries/CAPABILITY-GRAPH.yaml.
2. Find the matching top-level area (e.g., backend, frontend, ai-ml).
3. Add a new entry under sub_areas::

backend:
  sub_areas:
    - id: graphql_federation
      name: GraphQL Federation
      description: Apollo Federation + subgraph composition

1. Run python scripts/audit_semantic.py to confirm.
2. Now curated skills can reference graphql_federation in their sub_areas: list.

Naming convention

• id: lowercase + underscores, ≤30 chars
• name: human-readable title
• description: one sentence, ≤80 chars

Validation

python scripts/audit_semantic.py     # checks graph consistency
make audit                            # full gate