Conciseness

The body is dense with Foundry-specific knowledge Claude doesn't have (good), but several rules are repeated verbatim in multiple sections: the 50-character `--description` cap appears three times (top blockquote, step 3 callout, Common Pitfalls), the 'never Read/sed large spec files' rule appears in both Efficiency Rules and Common Pitfalls, and the 'only add x-cs-operation-config when asked' rule appears in step 3, the Expose section, and Pitfalls. This is noticeable duplication that could be consolidated. Not 2 because there is no explanation of concepts Claude already knows (OpenAPI, OAuth basics, etc.) and most sections earn their tokens; not 4 because the redundancy across three sections is more than minor trimming.

Actionability

Fully executable throughout: exact CLI commands (`foundry api-integrations create --name … --description … --spec … --no-prompt`), a venv setup block for the PEP 668 problem, a copy-paste python3 snippet for patching a single operation, complete YAML/JSON spec fragments, a runnable foundry-js calling example, and exact error strings ('input must be at most 50 characters long', '400 request failed schema validation: …') that enable precise failure matching. Common cases are covered end-to-end.

Workflow Clarity

The 'Download, Adapt, Register' workflow is explicitly ordered with numbered steps, includes an explicit validation checkpoint after registration ("Validate immediately after registering (`foundry apps validate --no-prompt`)"), an explicit error-recovery path when the adapt script gets a field wrong ("patch only that field and tell the user what the script missed"), guidance for the hook-blocked Swagger 2.0 case, and the deploy→lookup-ID→re-deploy loop for agent tools. The operation is not destructive, so no batch-validation cap applies.

Progressive Disclosure

Structure is real: a Reading Guide table maps tasks to the three reference files (all of which exist in the bundle), references are one level deep and well signaled, and the adapt script is properly bundled. However, the body cites `use-cases/http-actions.md`, `use-cases/greynoise-deep-dive.md`, and `use-cases/custom-soar-actions.md`, and no `use-cases/` directory exists in the bundle — three dangling references. Additionally, a fair amount of detail (the auth pattern table with prose, the full foundry-js example, server-URL variants) duplicates material that the reference files exist to hold. Not 4 because broken references exceed 'minor organization gaps'; not 2 because the core structure and navigation are genuinely good.

Specificity

The opening sentence names the domain and concrete action ("Expose external APIs to Falcon Foundry via OpenAPI specs"), and the trigger phrases enumerate several specific tasks (create, adapt an OpenAPI spec, expose an API to workflows, connect a third-party API, run the CLI command). Minor gaps: it doesn't mention the auth-configuration or registration/adaptation steps that make up the core workflow. Not 5 because the 'what' is carried largely by a single clause rather than a comprehensive list of capabilities; not 3 because the trigger list does name several concrete, distinct actions.

Completeness

Explicitly answers both: 'what' ("Expose external APIs to Falcon Foundry via OpenAPI specs") and 'when' with concrete trigger phrases ("TRIGGER when user asks to…", "Also trigger when user has an OpenAPI/Swagger spec and wants it working in Falcon Foundry"), plus a negative trigger. Matches the score-5 anchor exactly; not 4 because the 'when' is already fully explicit with multiple concrete phrases.

Trigger Term Quality

Comprehensive natural phrases users would actually say ("create an API integration", "connect to a third-party API", "expose an API to workflows") plus the exact CLI command `foundry api-integrations create`, and synonym coverage of both "OpenAPI" and "Swagger". Nothing a user would naturally say is missing.

Distinctiveness Conflict Risk

Clear niche (Falcon Foundry API integrations via OpenAPI specs) with an explicit disambiguation clause: "DO NOT TRIGGER when user wants to call Falcon platform APIs from function code — use functions-falcon-api instead." This actively prevents the most likely wrong-skill trigger; minimal conflict risk.