Skip to content

TypeSpec Authoring Skill for Azure

TypeSpec Authoring Skill for Azure

Section titled “TypeSpec Authoring Skill for Azure”

The “Azure TypeSpec Author” skill helps you write and update Azure API specifications using TypeSpec with confidence. It guides you through common authoring tasks, such as adding API versions and evolving existing specs, while ensuring your changes follow Azure standards, repository conventions, and validation rules, so your APIs are ready for review and SDK generation.

Set up environment

Section titled “Set up environment”

Copilot CLI Mode

Section titled “Copilot CLI Mode”
  1. Install the GitHub Copilot CLI by following the official installation guide.
  2. Launch a copilot CLI session from the root folder of https://github.com/Azure/azure-rest-api-specs in VSCode terminal.
  3. In the Copilot CLI session, input your prompts.

VSCode Agent Mode

Section titled “VSCode Agent Mode”
  1. Launch VSCode from the root folder of https://github.com/Azure/azure-rest-api-specs.
  2. Input prompts in the agent panel.

Sample prompts

Section titled “Sample prompts”

API Versioning

Section titled “API Versioning”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a new preview API version 2026-01-01-preview”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a new stable API version 2026-01-01”
  • “In specification/widget/resource-manager/Microsoft.Widget, Change visibility of provisioningState to Read+Create in 2025-05-04-preview only”
  • “In specification/widget/resource-manager/Microsoft.Widget, Change property age from required to optional in 2025-05-04-preview only”
  • “In the specification/widget/data-plane/WidgetAnalytics project, add a new preview version 2023-06-01-preview to the Versions enum.”
  • “In the specification/widget/data-plane/WidgetAnalytics project, add a new stable version 2023-06-01 to the Versions enum.”
  • “In the specification/widget/data-plane/WidgetAnalytics project, add a new optional description property of type string to the WidgetSuite model only for version 2023-06-01-preview. Also add this new version to the Versions enum.”
  • “In the specification/widget/data-plane/WidgetAnalytics project, rename the color property to widgetColor in the WidgetSuite model only for version 2023-06-01-preview. Also add this new version to the Versions enum.”

Resource Definitions

Section titled “Resource Definitions”
  • “In specification/widget/resource-manager/Microsoft.Widget add a new Tracked resource Asset with standard CRUD and list operations.”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a child resource named Component under the Asset resource”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a proxy resource named Config under the Asset resource”
  • “In specification/widget/resource-manager/Microsoft.Widget, change resource Employee as extension resource”

Resource Operations

Section titled “Resource Operations”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a custom action restartAsset to the Asset resource”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add an async/LRO operation to export data from the Asset resource”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a PATCH operation to the Asset resource”
  • “In specification/widget/resource-manager/Microsoft.Widget, Modify the LRO createOrUpdate PUT operation in interface employees so that it returns Azure-AsyncOperation header but NOT Retry-After header in the 201 response.”
  • “In the specification/widget/data-plane/WidgetAnalytics project, add a create or update operation for the WidgetSuite resource to the Widgets interface. The operation should allow creating or updating a Widget asynchronously”
  • “In the specification/widget/data-plane/WidgetAnalytics project, add a list operation for the WidgetSuite resource to the Widgets interface. The operation should allow listing Widget resources with standard list query parameters.”

Models & Types

Section titled “Models & Types”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add an enum named AssetStatus with values Active, Inactive, and Deprecated”
  • “In specification/widget/resource-manager/Microsoft.Widget, Add a new property tags to the Asset resource”

Getting Support

Section titled “Getting Support”

Any questions or feedbacks about using ‘TypeSpec Authoring Skill for Azure’ can be sent to the TypeSpec Discussion teams channel.