SKILL.md
$2a
@agent({
name: "[Agent Name]",
description: "[Description]"
})
@instructions("""
[Instructions for using the API operations]
""")
namespace [AgentName] {
// Reference operations from actions.tsp
op operation1 is [APINamespace].operationName;
}
### actions.tsp - API Operations
import "@typespec/http";
import "@microsoft/typespec-m365-copilot";
using TypeSpec.Http;
using TypeSpec.M365.Copilot.Actions;
@service
@actions(#{
nameForHuman: "[API Display Name]",
descriptionForModel: "[Model description]",
descriptionForHuman: "[User description]"
})
@server("[API_BASE_URL]", "[API Name]")
@useAuth([AuthType]) // Optional
namespace [APINamespace] {
@route("[/path]")
@get
@action
op operationName(
@path param1: string,
@query param2?: string
): ResponseModel;
model ResponseModel {
// Response structure
}
}
## Authentication Options
Choose based on API requirements:
-
**No Authentication** (Public APIs)
// No @useAuth decorator needed
-
**API Key**
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
-
**OAuth2**
@useAuth(OAuth2Auth<[{
type: OAuth2FlowType.authorizationCode;
authorizationUrl: "https://oauth.example.com/authorize";
tokenUrl: "https://oauth.example.com/token";
refreshUrl: "https://oauth.example.com/token";
scopes: ["read", "write"];
}]>)
-
**Registered Auth Reference**
@useAuth(Auth)
@authReferenceId("registration-id-here")
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">
## 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.
""")