Existing skills: apply-policy-to-api-instance and protect-api-with-policies have overlapping scope and competing triggers

[tbolis-at-mulesoft]

Problem

skills/apply-policy-to-api-instance/SKILL.md and skills/protect-api-with-policies/SKILL.md
overlap in both workflow and trigger phrasing. An agent reading the two descriptions has no
reliable way to pick between them for prompts like "apply a rate limit to my API" or "protect
my API with OAuth2" — both skills claim those cases.

Evidence of overlap

Shared core workflow (same operations, same APIs):

• listEnvironments on urn:api:access-management
• getExchangePolicyTemplates on urn:api:api-portal-xapi (both pass includeConfiguration: true, latest: true, and filter by apiInstanceId + environmentId)
• createOrganizationsEnvironmentsApisPolicies on urn:api:api-manager

protect-api-with-policies self-declares the overlap:

Apply policy only: Steps 2, 6, 7 — When: You already have an API Manager instance and want
to apply a policy

That path is functionally apply-policy-to-api-instance minus the instance-picker step
(listOrganizationsEnvironmentsApis).

Competing descriptions (front-matter):

• apply-policy-to-api-instance: "Use when the user wants to add a policy, enforce security,
  configure rate limiting, apply OAuth2, set up IP allowlisting, or protect an API with any policy
  template from the catalog."
• protect-api-with-policies: "Use when the user wants to secure an API, add rate limiting,
  apply OAuth2, enforce IP allowlisting, or protect any API with a policy — regardless of where
  they are in the setup process."

Both claim rate limiting, OAuth2, IP allowlisting, and "protect an API."

Key differences (so this isn't a pure duplicate)

• protect-api-with-policies covers the full Flex-Gateway end-to-end path: publish to Exchange
  (createAssets), pick a gateway target (getGatewayTargets), create the API Manager instance
  (createOrganizationsEnvironmentsApis), and deploy via urn:api:proxies-xapi (HY deployment
  type).
• protect-api-with-policies is Flex-Gateway-specific (hardcodes technology: flexGateway,
  type: "HY", gatewayVersion: "1.0.0").
• apply-policy-to-api-instance is gateway-agnostic and includes
  listOrganizationsEnvironmentsApis to let the user pick the instance — which
  protect-api-with-policies lacks even on its "apply only" path.

Proposed resolution (pick one)

1. Merge — Keep protect-api-with-policies as the single skill with explicit execution
   paths, and delete apply-policy-to-api-instance. Add the missing
   listOrganizationsEnvironmentsApis step to the "apply only" path so users without a known
   environmentApiId are still covered.
2. Sharpen boundaries — Keep both, but rewrite the description: front-matter so they don't
   compete:
   • apply-policy-to-api-instance: strictly "apply a policy to an existing API Manager
     instance — gateway-agnostic". Remove "protect an API" and OAuth2/rate-limiting verbs from the
     trigger list.
   • protect-api-with-policies: strictly "end-to-end Flex-Gateway protection including
     publish, deploy, and policy". Remove the "apply policy only" path and point users at
     apply-policy-to-api-instance instead.

Option 2 is lower-risk; option 1 is cleaner long-term.

Acceptance criteria

• An agent given "apply rate limiting to my existing API" picks exactly one skill with no
  ambiguity
• An agent given "I have an OAS file and want to publish, deploy to Flex Gateway, and apply
  OAuth2" picks exactly one skill
• The two skills' description: fields share no verb phrases that would trigger both
• python3 scripts/build/validate_jtbd.py skills/<name>/SKILL.md . passes for both files