MR
Mayur Rathi
@github
⭐ 34.1k GitHub stars

Typespec-M365-Copilot

Typespec-M365-Copilot是一款code方向的AI技能，核心价值是Guidelines and best practices for building TypeSpec-based declarative agents and API plugins for Microsoft 365 Copilot，可用于解决开发者在code领域的实际问题，帮助用户提升效率、自动化重复任务或优化工作流。

Guidelines and best practices for building TypeSpec-based declarative agents and API plugins for Microsoft 365 Copilot

Last verified on: 2026-05-30
mkdir -p ./skills/typespec-m365-copilot && curl -sfL https://raw.githubusercontent.com/github/awesome-copilot/main/skills/typespec-m365-copilot/SKILL.md -o ./skills/typespec-m365-copilot/SKILL.md

Run in terminal / PowerShell. Requires curl (Unix) or PowerShell 5+ (Windows).

Skill Content

# TypeSpec for Microsoft 365 Copilot Development Guidelines


Core Principles


When working with TypeSpec for Microsoft 365 Copilot:


1. **Type Safety First**: Leverage TypeSpec's strong typing for all models and operations

2. **Declarative Approach**: Use decorators to describe intent, not implementation

3. **Scoped Capabilities**: Always scope capabilities to specific resources when possible

4. **Clear Instructions**: Write explicit, detailed agent instructions

5. **User-Centric**: Design for the end-user experience in Microsoft 365 Copilot


File Organization


Standard Structure

text 
project/
├── appPackage/
│   ├── cards/              # Adaptive Card templates
│   │   └── *.json
│   ├── .generated/         # Generated manifests (auto-generated)
│   └── manifest.json       # Teams app manifest
├── src/
│   ├── main.tsp           # Agent definition
│   └── actions.tsp        # API operations (for plugins)
├── m365agents.yml         # Agents Toolkit configuration
└── package.json

Import Statements

Always include required imports at the top of TypeSpec files:


typescript 
import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;  // For agents
using TypeSpec.M365.Copilot.Actions; // For API plugins

Agent Development Best Practices


Agent Declaration

typescript 
@agent({
  name: "Role-Based Name",  // e.g., "Customer Support Assistant"
  description: "Clear, concise description under 1,000 characters"
})

- Use role-based names that describe what the agent does

- Make descriptions informative but concise

- Avoid generic names like "Helper" or "Bot"


Instructions

typescript 
@instructions("""
  You are a [specific role] specialized in [domain].
  
  Your responsibilities include:
  - [Key responsibility 1]
  - [Key responsibility 2]
  
  When helping users:
  - [Behavioral guideline 1]
  - [Behavioral guideline 2]
  
  You should NOT:
  - [Constraint 1]
  - [Constraint 2]
""")

- Write in second person ("You are...")

- Be specific about the agent's role and expertise

- Define both what to do AND what not to do

- Keep under 8,000 characters

- Use clear, structured formatting


Conversation Starters

typescript 
@conversationStarter(#{
  title: "Action-Oriented Title",  // e.g., "Check Status"
  text: "Specific example query"   // e.g., "What's the status of my ticket?"
})

- Provide 2-4 diverse starters

- Make each showcase a different capability

- Use action-oriented titles

- Write realistic example queries


Capabilities - Knowledge Sources


**Web Search** - Scope to specific sites when possible:

typescript 
op webSearch is AgentCapabilities.WebSearch<Sites = [
  { url: "https://learn.microsoft.com" },
  { url: "https://docs.microsoft.com" }
]>;

**OneDrive and SharePoint** - Use URLs or IDs:

typescript 
op oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint<
  ItemsByUrl = [
    { url: "https://contoso.sharepoint.com/sites/Engineering" }
  ]
>;

**Teams Messages** - Specify channels/chats:

typescript 
op teamsMessages is AgentCapabilities.TeamsMessages<Urls = [
  { url: "https://teams.microsoft.com/l/channel/..." }
]>;

**Email** - Scope to specific folders:

typescript 
op email is AgentCapabilities.Email<
  Folders = [
    { folderId: "Inbox" },
    { folderId: "SentItems" }
  ],
  SharedMailbox = "support@contoso.com"  // Optional
>;

**People** - No scoping needed:

typescript 
op people is AgentCapabilities.People;

**Copilot Connectors** - Specify connection IDs:

typescript 
op copilotConnectors is AgentCapabilities.GraphConnectors<
  Connections = [
    { connectionId: "your-connector-id" }
  ]
>;

**Dataverse** - Scope to specific tables:

typescript 
op dataverse is AgentCapabilities.Dataverse<
  KnowledgeSources = [
    {
      hostName: "contoso.crm.dynamics.com";
      tables: [
        { tableName: "account" },

🎯 Best For

  • UI designers
  • Product designers
  • Claude users
  • GitHub Copilot users
  • Software engineers

💡 Use Cases

  • Generating component mockups
  • Creating design system tokens
  • Code quality improvement
  • Best practice enforcement

📖 How to Use This Skill

  1. 1

    Install the Skill

    Copy the install command from the Terminal tab and run it. The SKILL.md file downloads to your local skills directory.

  2. 2

    Load into Your AI Assistant

    Open Claude or GitHub Copilot and reference the skill. Paste the SKILL.md content or use the system prompt tab.

  3. 3

    Apply Typespec-M365-Copilot to Your Work

    Open your project in the AI assistant and ask it to apply the skill. Start with a small module to verify the output quality.

  4. 4

    Review and Refine

    Review AI suggestions before committing. Run tests, check for regressions, and iterate on the skill output.

❓ Frequently Asked Questions

Does this work with Figma?

Some design skills integrate with Figma plugins. Check the Works With section for supported tools.

Is Typespec-M365-Copilot compatible with Cursor and VS Code?

Yes — this skill works with any AI coding assistant including Cursor, VS Code with Copilot, and JetBrains IDEs.

Do I need specific dependencies for Typespec-M365-Copilot?

Check the install command and Works With section. Most code skills only require the AI assistant and your codebase.

How do I install Typespec-M365-Copilot?

Copy the install command from the Terminal tab and run it. The skill downloads to ./skills/typespec-m365-copilot/SKILL.md, ready to use.

Can I customize this skill for my team?

Absolutely. Edit the SKILL.md file to add team-specific instructions, examples, or workflows.

⚠️ Common Mistakes to Avoid

Skipping usability testing

AI-generated designs should be validated with real users before development.

Skipping validation

Always test AI-generated code changes, even for simple refactors.

Missing dependency updates

Check if the skill requires updated dependencies or new packages.

🔗 Related Skills

00-andruia-consultant 00-andruia-consultant007 00710-andruia-skill-smith 10-andruia-skill-smith20-andruia-niche-intelligence 20-andruia-niche-intelligencea11y A11Yaccessibility Accessibility Expert