Validates that all TypeSpec route operations in the AI Foundry data-plane (Foundry) domain have documentation comments and @summary decorators with correct voice, replaces documentation-required suppressions with generated documentation, and uses description override extensions when TypeSpec would concatenate noisy descriptions. USE FOR: reviewing or authoring routes.tsp and routes.generated.tsp files under specification/ai-foundry/data-plane/Foundry/src/, including nested OpenAI routes under src/openai/. DO NOT USE FOR: files outside the Foundry data-plane area, model-only .tsp files, or SDK client customization files (client.tsp).
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Validates that all TypeSpec route operations in the AI Foundry data-plane (Foundry) domain have documentation comments and @summary decorators with correct voice, replaces documentation-required suppressions with generated documentation, and uses description override extensions when TypeSpec would concatenate noisy descriptions. USE FOR: reviewing or authoring routes.tsp and routes.generated.tsp files under specification/ai-foundry/data-plane/Foundry/src/, including nested OpenAI routes under src/openai/. DO NOT USE FOR: files outside the Foundry data-plane area, model-only .tsp files, or SDK client customization files (client.tsp).
Foundry Route Documentation Check
Ensures every TypeSpec route operation in the AI Foundry data-plane (Foundry) area has
proper documentation comments and @summary decorator tags, using the correct grammatical
voice for each.
OpenAI route files are nested under specification/ai-foundry/data-plane/Foundry/src/openai/<area>/.
It does not apply to:
models.tsp, client.tsp, client.*.tsp, or files
main.tsp
Any .tsp files outside specification/ai-foundry/data-plane/Foundry/
Generated OpenAPI JSON under openapi3/
When to Use
Reviewing or authoring route definitions in the Foundry data-plane area
Pre-PR checks for missing API documentation
Auditing existing routes for documentation completeness
Conservative Change Policy
Do not modify documentation that is already substantially correct. Only flag and fix
operations that have an explicit, significant rule violation:
Missing @summary() or doc comment entirely → fix
Wrong grammatical voice (@summary using third-person, or doc comment using imperative) → fix
Empty or placeholder documentation → fix
Summary contains unnecessary filler ("all", "by id") that can be removed → fix
Summary uses a multiline triple-quoted string, full sentence, or paragraph instead of a concise single-line phrase → fix
Description is near-identical to the summary with no added detail → fix
Description uses @doc() instead of a TSDoc /** ... */ comment → fix
#suppress "@azure-tools/typespec-azure-core/documentation-required" ... hides missing route or parameter documentation → remove the suppression and add documentation
Multiple adjacent TSDoc comment blocks apply to the same operation or parameter → merge or remove the redundant block
Multiple route variants or content types would cause TypeSpec to concatenate request body or parameter descriptions into noisy OpenAPI text → add the appropriate override extension with the intended final description instead of stacking TSDoc comments
Minor wording preferences or stylistic differences that do not violate a rule → leave unchanged
When in doubt, leave the existing text alone.
For routes.generated.tsp files, it is acceptable to apply this skill's automated
rewrite directly to the generated file. The intended workflow is to run route
generation first and then run this rewrite immediately afterward, so the generated
route documentation changes are consistently reapplied and not lost overall.
Rules
Every operation defined inside an interface block in a routes.tsp or routes.generated.tsp file must satisfy
all of the following requirements. See route-documentation-rules.md
for the full rule definitions, examples, and remediation guidance.
Rule ID
Requirement
FDOC-001
Every operation must have a TSDoc /** ... */ comment. Prefer TSDoc over @doc().
FDOC-002
Every operation must have a @summary() decorator — no exceptions
FDOC-003
The TSDoc description must use third-person indicative voice ("Creates an agent"), must add meaningful detail beyond the summary, and must not be near-identical to the summary.
FDOC-004
@summary() must be a maximally concise, single-line imperative phrase ("Create an agent"). No multiline strings. No trailing period. No filler ("all", "by ID", "info about"). Must not be truncated. Always include articles.
FDOC-005
Each @path, @query, @header, and @body parameter must have a doc comment or @doc()
FDOC-006
Do not leave multiple adjacent TSDoc comment blocks on the same operation or parameter. TypeSpec concatenates adjacent docs into one OpenAPI description, which can produce malformed text.
FDOC-007
Remove documentation-required suppressions on routes and parameters, including auto-generated import suppressions, and replace them with generated TSDoc documentation.
FDOC-008
When TypeSpec would concatenate operation summaries/descriptions, request body descriptions, or parameter descriptions for shared routes, multiple content types, or adjacent imported docs, add the appropriate override extension with the desired final text.
documentation-required suppressions
When a route file contains a suppression for missing documentation, treat it as a fixable
documentation violation, not as an accepted exception. This includes suppressions such as:
#suppress "@azure-tools/typespec-azure-core/documentation-required" "Auto-suppressed warnings non-applicable rules during import."
For each matching suppression in a scoped routes.tsp or routes.generated.tsp file:
Remove the #suppress directive.
Identify the operation, operation parameter, request body, query/header/path parameter, or
route-related declaration the suppression was shielding.
Add or repair the appropriate TSDoc documentation using rules FDOC-001 through FDOC-005.
If the target already has a TSDoc comment or participates in a shared route / multiple-content-type request body where TypeSpec would concatenate descriptions, keep a single TSDoc comment for linter compliance and add the correct override extension.
For @path, @query, and real @header parameters, apply the parameter-level extension:
@extension("x-ms-description-override", "The intended final OpenAPI description.")
For @body and @multipartBody, apply an operation-level request-body override because
TypeSpec does not emit parameter-level extensions onto the OpenAPI requestBody object:
@extension("x-ms-request-body-description-override", "The intended final request body description.")
Put this operation-level extension with the operation decorators (near @summary, @route,
and @post). Import and use TypeSpec.OpenAPI if the file does not already do so.
Preserve unrelated suppressions and any non-documentation suppressions.
Do not leave the file in a state where documentation-required still needs to be suppressed.
Description override extensions
Use description override extensions when the source must retain documentation for TypeSpec
linting but the emitted OpenAPI description would otherwise be noisy because TypeSpec
concatenates multiple source descriptions.
Use:
x-ms-summary-override and x-ms-description-override on each shared-route
operation variant when TypeSpec would merge multiple operations into one OpenAPI
operation and concatenate their summaries/descriptions
x-ms-description-override on @path, @query, and real @header parameters
x-ms-request-body-description-override on the operation for @body and
@multipartBody request bodies
Common examples:
Shared-route operation variants that combine multipart and JSON request bodies into
one OpenAPI operation, causing summaries such as
"Create a video edit multipart Create a video edit json"
Shared-route request bodies that combine JSON and multipart content types into one OpenAPI requestBody
Imported generated parameters where the import already contributed a generic description
Any route parameter or request body that would emit repeated text such as "The request body.The request body." or "The file id path parameter.The ID of the file."
Prefer one concise TSDoc comment for the source declaration and one override extension with
the exact final OpenAPI text. Do not add adjacent TSDoc comments as a workaround. Do not add
x-ms-description-override directly to @body or @multipartBody declarations because the
OpenAPI emitter does not preserve those extensions on requestBody.
Post-Edit Steps
After applying fixes to any routes.tsp or routes.generated.tsp file, always run the following steps in order:
1. Format
Run tsp format on the changed files to ensure consistent formatting:
npx tsp format specification/ai-foundry/data-plane/Foundry/src/**/routes.tsp specification/ai-foundry/data-plane/Foundry/src/**/routes.generated.tsp
2. Regenerate OpenAPI artifacts
Recompile the project to regenerate both JSON and YAML OpenAPI outputs under openapi3/.
Do not modify tspconfig.yaml — it already emits both file types via file-type: [yaml, json].
cd specification/ai-foundry/data-plane/Foundry
npx tsp compile .
Verify that the files under openapi3/{version}/ are updated for every versioned output.
Workflow
Identify all routes.tsp and routes.generated.tsp files under specification/ai-foundry/data-plane/Foundry/src/
Parse each interface block and enumerate its operations
Check each operation against rules FDOC-001 through FDOC-008
Report findings grouped by file, with rule ID, operation name, and line number
Fix only operations with explicit, significant rule violations (see Conservative Change Policy)
Run tsp format on all modified files
Run tsp compile . to regenerate JSON and YAML OpenAPI artifacts
