/typespec-api-design

Microsoft 365 Copilot and App-as-Skill boundary bundle

Inherits hard rules from SKILL.md §Hard rules.

Use this bundle when the API may become a Microsoft 365 Copilot extension, declarative agent action, API plugin, MCP tool, or other agent-consumable surface.

Operation ID stability

Copilot tool definitions reference operation IDs as stable handles. Renaming an interface or operation rewrites the auto-generated operation ID (Interface_operationName) and breaks every existing Copilot action binding, declarative-agent manifest, and MCP tool registration that referenced the old name.

Treat operation-ID changes as breaking even in non-breaking API versions. If you need to rename for clarity, schedule the rename for the next major version cut and coordinate the manifest/tool-definition update with downstream Copilot/App-as-Skill owners.

Boundary rule

This skill owns the REST/API contract. A Microsoft 365 Copilot/App-as-Skill skill owns Copilot-specific manifests, action metadata, declarative agents, and @microsoft/typespec-m365-copilot decorators.

Do not mix Azure service decorators and Microsoft 365 Copilot decorators unless the target is explicitly a Microsoft 365 Copilot extension and the repository has the Copilot TypeSpec toolchain installed.

Handoff checks

Before routing onward:

• OpenAPI is generated from TypeSpec and not hand-edited.
• Operations are named with semantic intent.
• Parameters are documented, constrained, and not overloaded.
• Request and response bodies use named models.
• Authentication is explicit and compatible with the target platform.
• Destructive operations are clearly documented and, where appropriate, require an explicit confirmation field.
• Response payloads include enough information for an agent to explain results to a user.
• Error responses are predictable and include machine-readable codes.

Copilot-specific warning

TypeSpec for Microsoft 365 Copilot has its own specialized decorators and workflow. Use it only when building Microsoft 365 Copilot declarative agents/API plugins. For ordinary REST APIs, stay with @typespec/http, @typespec/rest, @typespec/openapi3, and Azure libraries where applicable.

Agent-consumability checks

The skill's agent boundary contract requires:

• Every operation has @doc with intent plus a side-effect classification: read, write, or destructive.
• Every input parameter has @doc. String parameters also have @minLength/@maxLength or @pattern so agents know valid input shapes.
• No anonymous response shapes - every response model is named. Copilot tooling references model names when wiring actions.
• No unknown or {} response bodies - agents cannot reason about untyped payloads.
• Operation IDs derive deterministically from Interface_operationName; do not set @operationId manually.
• For Microsoft 365 Copilot specifically, route to the dedicated Copilot / App-as-Skill skill once the contract is stable. This skill stops at the OpenAPI boundary.

Hand-off artifacts

When handing the API off to a Copilot agent author, deliver:

• The compiled OpenAPI 3.0 file emitted from TypeSpec.
• The examples/*.json files referenced by operations.
• A one-page intent doc per operation group covering purpose, side-effect class, and typical user phrasing.
• The OAuth2 flow plus a scopes table mapping each scope to the operations it unlocks.

Agent-ready design patterns

Prefer operations like:

• searchCustomers
• getCustomer
• listOrders
• createSupportTicket
• cancelBooking

Avoid vague operations like:

• execute
• process
• submit
• action

For actions with side effects, model intent explicitly:

/** Request to cancel a booking. */
model CancelBookingRequest {
  /** User-visible reason for cancellation. */
  reason: string;

  /** Explicit confirmation that the caller intends to cancel this booking. */
  confirmed: true;
}