typespec-create-api-plugin

Name: typespec-create-api-plugin
Author: github

8.6kinstalls4.6kforks

How to install typespec-create-api-plugin?

github/awesome-copilot/typespec-create-api-plugin

$npx -y skills add github/awesome-copilot --skill typespec-create-api-plugin

Installs into the current project.

Summary

Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot

Files · 1

View on GitHub

SKILL.md

1	# Create TypeSpec API Plugin
2
3	Create a complete TypeSpec API plugin for Microsoft 365 Copilot that integrates with external REST APIs.
4
5	## Requirements
6
7	Generate TypeSpec files with:
8
9	### main.tsp - Agent Definition
10	```typescript
11	import "@typespec/http";
12	import "@typespec/openapi3";
13	import "@microsoft/typespec-m365-copilot";
14	import "./actions.tsp";
15
16	using TypeSpec.Http;
17	using TypeSpec.M365.Copilot.Agents;
18	using TypeSpec.M365.Copilot.Actions;
19
20	@agent({
21	name: "[Agent Name]",
22	description: "[Description]"
23	})
24	@instructions("""
25	[Instructions for using the API operations]
26	""")
27	namespace [AgentName] {
28	// Reference operations from actions.tsp
29	op operation1 is [APINamespace].operationName;
30	}
31	```
32
33	### actions.tsp - API Operations
34	```typescript
35	import "@typespec/http";
36	import "@microsoft/typespec-m365-copilot";
37
38	using TypeSpec.Http;
39	using TypeSpec.M365.Copilot.Actions;
40
41	@service
42	@actions(#{
43	nameForHuman: "[API Display Name]",
44	descriptionForModel: "[Model description]",
45	descriptionForHuman: "[User description]"
46	})
47	@server("[API_BASE_URL]", "[API Name]")
48	@useAuth([AuthType]) // Optional
49	namespace [APINamespace] {
50
51	@route("[/path]")
52	@get
53	@action
54	op operationName(
55	@path param1: string,
56	@query param2?: string
57	): ResponseModel;
58
59	model ResponseModel {
60	// Response structure
61	}
62	}
63	```
64
65	## Authentication Options
66
67	Choose based on API requirements:
68
69	1. No Authentication (Public APIs)
70	```typescript
71	// No @useAuth decorator needed
72	```
73
74	2. API Key
75	```typescript
76	@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
77	```
78
79	3. OAuth2
80	```typescript
81	@useAuth(OAuth2Auth<[{
82	type: OAuth2FlowType.authorizationCode;
83	authorizationUrl: "https://oauth.example.com/authorize";
84	tokenUrl: "https://oauth.example.com/token";
85	refreshUrl: "https://oauth.example.com/token";
86	scopes: ["read", "write"];
87	}]>)
88	```
89
90	4. Registered Auth Reference
91	```typescript
92	@useAuth(Auth)
93
94	@authReferenceId("registration-id-here")
95	model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">
96	```
97
98	## Function Capabilities
99
100	### Confirmation Dialog
101	```typescript
102	@capabilities(#{
103	confirmation: #{
104	type: "AdaptiveCard",
105	title: "Confirm Action",
106	body: """
107	Are you sure you want to perform this action?
108	* Parameter: {{ function.parameters.paramName }}
109	"""
110	}
111	})
112	```
113
114	### Adaptive Card Response
115	```typescript
116	@card(#{
117	dataPath: "$.items",
118	title: "$.title",
119	url: "$.link",
120	file: "cards/card.json"
121	})
122	```
123
124	### Reasoning & Response Instructions
125	```typescript
126	@reasoning("""
127	Consider user's context when calling this operation.
128	Prioritize recent items over older ones.
129	""")
130	@responding("""
131	Present results in a clear table format with columns: ID, Title, Status.
132	Include a summary count at the end.
133	""")
134	```
135
136	## Best Practices
137
138	1. Operation Names: Use clear, action-oriented names (listProjects, createTicket)
139	2. Models: Define TypeScript-like models for requests and responses
140	3. HTTP Methods: Use appropriate verbs (@get, @post, @patch, @delete)
141	4. Paths: Use RESTful path conventions with @route
142	5. Parameters: Use @path, @query, @header, @body appropriately
143	6. Descriptions: Provide clear descriptions for model understanding
144	7. Confirmations: Add for destructive operations (delete, update critical data)
145	8. Cards: Use for rich visual responses with multiple data items
146
147	## Workflow
148
149	Ask the user:
150	1. What is the API base URL and purpose?
151	2. What operations are needed (CRUD operations)?
152	3. What authentication method does the API use?
153	4. Should confirmations be required for any operations?
154	5. Do responses need Adaptive Cards?
155
156	Then generate:
157	- Complete `main.tsp` with agent definition
158	- Complete `actions.tsp` with API operations and models
159	- Optional `cards/card.json` if Adaptive Cards are needed

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

typespec-create-api-plugin

8.6kinstalls4.6kforks

View on GitHub

How to install typespec-create-api-plugin?

github/awesome-copilot/typespec-create-api-plugin

$npx -y skills add github/awesome-copilot --skill typespec-create-api-plugin

Installs into the current project.

Summary

Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot

Files · 1

View on GitHub

SKILL.md

1	# Create TypeSpec API Plugin
2
3	Create a complete TypeSpec API plugin for Microsoft 365 Copilot that integrates with external REST APIs.
4
5	## Requirements
6
7	Generate TypeSpec files with:
8
9	### main.tsp - Agent Definition
10	```typescript
11	import "@typespec/http";
12	import "@typespec/openapi3";
13	import "@microsoft/typespec-m365-copilot";
14	import "./actions.tsp";
15
16	using TypeSpec.Http;
17	using TypeSpec.M365.Copilot.Agents;
18	using TypeSpec.M365.Copilot.Actions;
19
20	@agent({
21	name: "[Agent Name]",
22	description: "[Description]"
23	})
24	@instructions("""
25	[Instructions for using the API operations]
26	""")
27	namespace [AgentName] {
28	// Reference operations from actions.tsp
29	op operation1 is [APINamespace].operationName;
30	}
31	```
32
33	### actions.tsp - API Operations
34	```typescript
35	import "@typespec/http";
36	import "@microsoft/typespec-m365-copilot";
37
38	using TypeSpec.Http;
39	using TypeSpec.M365.Copilot.Actions;
40
41	@service
42	@actions(#{
43	nameForHuman: "[API Display Name]",
44	descriptionForModel: "[Model description]",
45	descriptionForHuman: "[User description]"
46	})
47	@server("[API_BASE_URL]", "[API Name]")
48	@useAuth([AuthType]) // Optional
49	namespace [APINamespace] {
50
51	@route("[/path]")
52	@get
53	@action
54	op operationName(
55	@path param1: string,
56	@query param2?: string
57	): ResponseModel;
58
59	model ResponseModel {
60	// Response structure
61	}
62	}
63	```
64
65	## Authentication Options
66
67	Choose based on API requirements:
68
69	1. No Authentication (Public APIs)
70	```typescript
71	// No @useAuth decorator needed
72	```
73
74	2. API Key
75	```typescript
76	@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
77	```
78
79	3. OAuth2
80	```typescript
81	@useAuth(OAuth2Auth<[{
82	type: OAuth2FlowType.authorizationCode;
83	authorizationUrl: "https://oauth.example.com/authorize";
84	tokenUrl: "https://oauth.example.com/token";
85	refreshUrl: "https://oauth.example.com/token";
86	scopes: ["read", "write"];
87	}]>)
88	```
89
90	4. Registered Auth Reference
91	```typescript
92	@useAuth(Auth)
93
94	@authReferenceId("registration-id-here")
95	model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">
96	```
97
98	## Function Capabilities
99
100	### Confirmation Dialog
101	```typescript
102	@capabilities(#{
103	confirmation: #{
104	type: "AdaptiveCard",
105	title: "Confirm Action",
106	body: """
107	Are you sure you want to perform this action?
108	* Parameter: {{ function.parameters.paramName }}
109	"""
110	}
111	})
112	```
113
114	### Adaptive Card Response
115	```typescript
116	@card(#{
117	dataPath: "$.items",
118	title: "$.title",
119	url: "$.link",
120	file: "cards/card.json"
121	})
122	```
123
124	### Reasoning & Response Instructions
125	```typescript
126	@reasoning("""
127	Consider user's context when calling this operation.
128	Prioritize recent items over older ones.
129	""")
130	@responding("""
131	Present results in a clear table format with columns: ID, Title, Status.
132	Include a summary count at the end.
133	""")
134	```
135
136	## Best Practices
137
138	1. Operation Names: Use clear, action-oriented names (listProjects, createTicket)
139	2. Models: Define TypeScript-like models for requests and responses
140	3. HTTP Methods: Use appropriate verbs (@get, @post, @patch, @delete)
141	4. Paths: Use RESTful path conventions with @route
142	5. Parameters: Use @path, @query, @header, @body appropriately
143	6. Descriptions: Provide clear descriptions for model understanding
144	7. Confirmations: Add for destructive operations (delete, update critical data)
145	8. Cards: Use for rich visual responses with multiple data items
146
147	## Workflow
148
149	Ask the user:
150	1. What is the API base URL and purpose?
151	2. What operations are needed (CRUD operations)?
152	3. What authentication method does the API use?
153	4. Should confirmations be required for any operations?
154	5. Do responses need Adaptive Cards?
155
156	Then generate:
157	- Complete `main.tsp` with agent definition
158	- Complete `actions.tsp` with API operations and models
159	- Optional `cards/card.json` if Adaptive Cards are needed

People who liked this also viewed

6 picks

Type