Index of every page on this site: llms.txt
All skills
github avatar

/typespec-create-api-plugin

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

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

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/typespec-create-api-plugin

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈35 tokens for metadata: the name and description. ≈970 when used: this file.

Description uses 1.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈142 characters, or 1.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Create TypeSpec API Plugin

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

Requirements

Generate TypeSpec files with:

main.tsp - Agent Definition

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@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:

  1. No Authentication (Public APIs)

    // No @useAuth decorator needed
  2. API Key

    @useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)
  3. 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"];
    }]>)
  4. 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.
""")

Best Practices

  1. Operation Names: Use clear, action-oriented names (listProjects, createTicket)
  2. Models: Define TypeScript-like models for requests and responses
  3. HTTP Methods: Use appropriate verbs (@get, @post, @patch, @delete)
  4. Paths: Use RESTful path conventions with @route
  5. Parameters: Use @path, @query, @header, @body appropriately
  6. Descriptions: Provide clear descriptions for model understanding
  7. Confirmations: Add for destructive operations (delete, update critical data)
  8. Cards: Use for rich visual responses with multiple data items

Workflow

Ask the user:

  1. What is the API base URL and purpose?
  2. What operations are needed (CRUD operations)?
  3. What authentication method does the API use?
  4. Should confirmations be required for any operations?
  5. 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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides templates and instructions for generating TypeSpec-based API plugins for Microsoft 365 Copilot. It follows official Microsoft and TypeSpec development practices for API definitions, authentication, and user interaction controls. No security risks were detected.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 7 months ago
  • typespec
  • microsoft-365-copilot
  • api-plugin
  • rest
  • adaptive-cards
  • authentication
  • openapi

README badge

README badge for github/awesome-copilot/typespec-create-api-plugin

Generates TypeSpec API plugins for Microsoft 365 Copilot, including REST operation definitions, authentication configuration, and Adaptive Card responses. Used to scaffold plugin files (main.tsp, actions.tsp) that connect external APIs to Copilot agents with confirmation dialogs and formatted output.

Generated from the current SKILL.md.

What authentication methods does this skill support?
The skill supports no authentication (public APIs), API key authentication, OAuth2 with authorization code flow, and registered auth references. Choose based on your API's requirements.
Does this skill generate Adaptive Cards?
Yes. The skill can generate optional Adaptive Card templates for rich visual responses. Cards are configured via the @card decorator and reference a cards/card.json file.
What REST HTTP methods can the skill generate?
The skill supports standard REST verbs: @get, @post, @patch, and @delete. Operations are defined in actions.tsp with appropriate route paths and parameter decorators.
Can this skill add confirmation dialogs to operations?
Yes. The skill can add confirmation dialogs for destructive operations using the @capabilities decorator with AdaptiveCard type, allowing you to prompt users before executing actions like delete or update.

Generated from the current SKILL.md. These answers refresh after source changes.