Improve OAS

Add descriptions, examples, and code samples to a Kibana API area so that the generated OpenAPI specification is complete and useful for humans and AI agents.

This skill operates on any package or plugin in the Kibana repo. It detects how the plugin generates its OAS contribution and adapts accordingly. For issue categorization, use debug-oas.

Required interaction flow

1. Ask which API area the developer wants to improve (e.g. "fleet", "alerting", "streams").
2. Ask for the plugin or package directory path if not obvious from the API area.
3. Run discovery to detect the plugin's OAS approach.
4. Run debug-oas to get the current issue list and baseline count.
5. Present a summary of what needs to be done: how many routes, which categories of work (descriptions, examples, code samples, deprecation markers).
6. Implement changes route-by-route, bundling all improvements for one endpoint together.
7. After completing all routes, run validation to confirm the issue count dropped to zero (or to the expected residual).

Do not skip steps 1-2 unless the developer already provided the API area and path.

Phase 1: Discovery