typespec-create-api-plugin

by github

Generate TypeSpec API plugins for Microsoft 365 Copilot with REST operations, authentication, and Adaptive Cards. Scaffolds complete TypeSpec projects with agent definitions (main.tsp) and API operations (actions.tsp) following Microsoft 365 Copilot conventions Supports four authentication modes: public APIs, API key headers, OAuth2 with authorization code flow, and registered auth references Includes optional confirmation dialogs for destructive operations and Adaptive Card templates for... npx skills add https://github.com/github/awesome-copilot --skill typespec-create-api-plugin Download ZIPGitHub36.2k

Create TypeSpec API Plugin

Create a complete TypeSpec API plugin for Microsoft 365 Copilot that integrates with external REST APIs.

Authentication Options

Choose based on API requirements:

No Authentication (Public APIs)

// No @useAuth decorator needed

API Key

@useAuth(ApiKeyAuth )

OAuth2

@useAuth(OAuth2Auth )

Registered Auth Reference

@useAuth(Auth)

@authReferenceId("registration-id-here")
model Auth is ApiKeyAuth 

Function Capabilities

Confirmation Dialog

@capabilities(#{
 confirmation: #{
 type: "AdaptiveCard",
 title: "Confirm Action",
 body: """
 Are you sure you want to perform this action?
 * **Parameter**: {{ function.parameters.paramName }}
 """
 }
})

Adaptive Card Response

@card(#{
 dataPath: "$.items",
 title: "$.title",
 url: "$.link",
 file: "cards/card.json"
})

Reasoning & Response Instructions

@reasoning("""
 Consider user's context when calling this operation.
 Prioritize recent items over older ones.
""")
@responding("""
 Present results in a clear table format with columns: ID, Title, Status.
 Include a summary count at the end.
""")

Best Practices

• Operation Names: Use clear, action-oriented names (listProjects, createTicket)

• Models: Define TypeScript-like models for requests and responses

• HTTP Methods: Use appropriate verbs (@get, @post, @patch, @delete)

• Paths: Use RESTful path conventions with @route

• Parameters: Use @path, @query, @header, @body appropriately

• Descriptions: Provide clear descriptions for model understanding

• Confirmations: Add for destructive operations (delete, update critical data)

• Cards: Use for rich visual responses with multiple data items

Workflow

Ask the user:

• What is the API base URL and purpose?

• What operations are needed (CRUD operations)?

• What authentication method does the API use?

• Should confirmations be required for any operations?

• Do responses need Adaptive Cards?

Then generate:

• Complete main.tsp with agent definition

• Complete actions.tsp with API operations and models

• Optional cards/card.json if Adaptive Cards are needed