Azure TypeSpec Author

Quick Reference

Property	Value
Services	Azure TypeSpec API Specifications (ARM & Data-plane)
MCP Tools	azsdk_typespec_generate_authoring_plan, azsdk_run_typespec_validation
Best For	Authoring, modifying, and troubleshooting .tsp files

When to Use This Skill

• Creating, modifying, or deleting content in .tsp files
• API versioning (adding preview or stable versions)
• ARM or data-plane resource definitions (tracked, proxy, extension, child resources)
• Resource operations (CRUD, PATCH, custom actions, async/LRO)
• Models, enums, unions, properties, decorators, and constraints
• Swagger-to-TypeSpec conversion follow-up

MCP Tools

Tool	Command	Use
azsdk_typespec_generate_authoring_plan	Generate authoring plan	Produces a grounded plan for TypeSpec changes based on user request and existing code
azsdk_run_typespec_validation	Run validation	Runs TypeSpec compilation and lint validation after edits

---

Operating Principles

Non-negotiable — all principles below apply to every invocation of this skill.

1. This skill is MANDATORY for ALL .tsp file edits. Any request that modifies, creates, or deletes content in a .tsp file MUST follow the full workflow — regardless of how simple the change appears. There are no "trivial" TypeSpec edits. Even changing a single ? (optional → required) can be a breaking change requiring versioning decorators.
2. Do not edit any files until you have required inputs and have retrieved a solution. Use the azsdk_typespec_generate_authoring_plan MCP tool.
3. Make minimal, scoped edits to satisfy the request. Avoid refactors unless explicitly asked.
4. After edits, validate using the azsdk_run_typespec_validation MCP tool and report results.
5. Always provide references (titles / sections / links) from retrieved context that justify the recommended approach.

---

Workflow Steps

All 6 steps are MANDATORY. Do NOT skip any step.

Step	Name	Tool / File	Gate
1	Intake & Clarification	references/intake-arm.md	All inputs collected + analysis displayed
2	Retrieve Solution	azsdk_typespec_generate_authoring_plan	Grounded plan returned
3	Apply Changes	Editor	User confirms uncertainties
4	Validate	azsdk_run_typespec_validation	Compilation passes
5	Summarize	—	Summary displayed to user
6	Next Steps	references/next-steps-arm.md	Follow-up actions presented

---

Step 1: Intake & Clarification

Follow references/intake-arm.md to gather all required inputs.

Do NOT proceed to Step 2 until all required inputs are collected and the analysis output has been displayed.

---

Step 2: Retrieve Solution

Invoke azsdk_typespec_generate_authoring_plan MCP tool:

Parameter	Value
request	User request (verbatim)
additionalInformation	All content gathered from Step 1 (intake analysis, user answers, relevant .tsp code read from the project)
typeSpecProjectRootPath	TypeSpec project root path

Do NOT proceed to Step 3 without a grounded plan from this tool.

---

Step 3: Apply Changes

Only after a grounded plan is produced:

1. Confirm with user if any uncertainties remain
2. Make the minimal changes required in the relevant .tsp files
3. Prefer the official template/pattern from retrieved context even if the repo has older patterns

---

Step 4: Validate

Invoke azsdk_run_typespec_validation MCP tool to run validation.

• If validation passes → proceed to Step 5
• If validation fails → fix forward with minimal changes and re-validate
• Do NOT skip validation even if the change appears trivial

---

Step 5: Summarize

Return the following to the user:

Item	Detail
Files changed	List of modified files
What changed	Brief description of changes and rationale
Validation results	Pass/fail + key output
References	Titles/sections/links from the azure-sdk-mcp/azsdk_typespec_generate_authoring_plan tool response (do not omit this even for small or trivial changes) that justify decisions

---

Step 6: Next Steps

Read the file references/next-steps-arm.md (using the read_file tool) and execute ALL of its instructions.

Do NOT summarize and end your turn without presenting the follow-up actions from references/next-steps-arm.md to the user. The user must be given the opportunity to request additional changes.

---

Related Skills & References

Resource	Purpose
references/intake-arm.md	Step 1 — Intake and clarification steps for ARM authoring
references/next-steps-arm.md	Step 6 — Post-authoring follow-up actions and case-specific guidance
sdk-generation skill	SDK generation from TypeSpec
check-package-readiness skill	Release readiness checks