declarative-agents-microsoft365

Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows Triggers on: **.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json

16 stars

bydiegosouzapw

View on GitHub Installation ↓

Best use case

declarative-agents-microsoft365 is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using declarative-agents-microsoft365 should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/declarative-agents-microsoft365/SKILL.md --create-dirs "https://raw.githubusercontent.com/diegosouzapw/awesome-omni-skill/main/skills/tools/declarative-agents-microsoft365/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/declarative-agents-microsoft365/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How declarative-agents-microsoft365 Compares

Feature / Agent	declarative-agents-microsoft365	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

# Microsoft 365 Declarative Agents Development Guidelines

## Overview

Microsoft 365 Copilot declarative agents are powerful custom AI assistants that extend Microsoft 365 Copilot with specialized capabilities, enterprise data access, and custom behaviors. These guidelines provide comprehensive development practices for creating production-ready agents using the latest v1.5 JSON schema specification with full Microsoft 365 Agents Toolkit integration.

## Schema Specification v1.5

### Core Properties

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
  "version": "v1.5",
  "name": "string (max 100 characters)",
  "description": "string (max 1000 characters)", 
  "instructions": "string (max 8000 characters)",
  "capabilities": ["array (max 5 items)"],
  "conversation_starters": ["array (max 4 items, optional)"]
}
```

### Character Limits & Constraints
- **Name**: Maximum 100 characters, required
- **Description**: Maximum 1000 characters, required  
- **Instructions**: Maximum 8000 characters, required
- **Capabilities**: Maximum 5 items, minimum 1 item
- **Conversation Starters**: Maximum 4 items, optional

## Available Capabilities

### Core Capabilities
1. **WebSearch**: Internet search and real-time information access
2. **OneDriveAndSharePoint**: File access, document search, content management
3. **GraphConnectors**: Enterprise data integration from third-party systems
4. **MicrosoftGraph**: Access to Microsoft 365 services and data

### Communication & Collaboration
5. **TeamsAndOutlook**: Teams chat, meetings, email integration
6. **CopilotForMicrosoft365**: Advanced Copilot features and workflows

### Business Applications
7. **PowerPlatform**: Power Apps, Power Automate, Power BI integration
8. **BusinessDataProcessing**: Advanced data analysis and processing
9. **WordAndExcel**: Document creation, editing, analysis
10. **EnterpriseApplications**: Third-party business system integration
11. **CustomConnectors**: Custom API and service integrations

## Microsoft 365 Agents Toolkit Integration

### VS Code Extension Setup
```bash
# Install Microsoft 365 Agents Toolkit
# Extension ID: teamsdevapp.ms-teams-vscode-extension
```

### TypeSpec Development Workflow

#### 1. Modern Agent Definition
```typespec
import "@typespec/json-schema";

using TypeSpec.JsonSchema;

@jsonSchema("/schemas/declarative-agent/v1.5/schema.json")
namespace DeclarativeAgent;

/** Microsoft 365 Declarative Agent */
model Agent {
  /** Schema version */
  @minLength(1)
  $schema: "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json";
  
  /** Agent version */
  version: "v1.5";
  
  /** Agent name (max 100 characters) */
  @maxLength(100)
  @minLength(1)
  name: string;
  
  /** Agent description (max 1000 characters) */
  @maxLength(1000)
  @minLength(1)  
  description: string;
  
  /** Agent instructions (max 8000 characters) */
  @maxLength(8000)
  @minLength(1)
  instructions: string;
  
  /** Agent capabilities (1-5 items) */
  @minItems(1)
  @maxItems(5)
  capabilities: AgentCapability[];
  
  /** Conversation starters (max 4 items) */
  @maxItems(4)
  conversation_starters?: ConversationStarter[];
}

/** Available agent capabilities */
union AgentCapability {
  "WebSearch",
  "OneDriveAndSharePoint", 
  "GraphConnectors",
  "MicrosoftGraph",
  "TeamsAndOutlook",
  "PowerPlatform",
  "BusinessDataProcessing",
  "WordAndExcel",
  "CopilotForMicrosoft365",
  "EnterpriseApplications",
  "CustomConnectors"
}

/** Conversation starter definition */
model ConversationStarter {
  /** Starter text (max 100 characters) */
  @maxLength(100)
  @minLength(1)
  text: string;
}
```

#### 2. Compilation to JSON
```bash
# Compile TypeSpec to JSON manifest
tsp compile agent.tsp --emit=@typespec/json-schema
```

### Environment Configuration

#### Development Environment
```json
{
  "name": "${DEV_AGENT_NAME}",
  "description": "Development version: ${AGENT_DESCRIPTION}",
  "instructions": "${AGENT_INSTRUCTIONS}",
  "capabilities": ["${REQUIRED_CAPABILITIES}"]
}
```

#### Production Environment
```json
{
  "name": "${PROD_AGENT_NAME}",
  "description": "${AGENT_DESCRIPTION}",
  "instructions": "${AGENT_INSTRUCTIONS}",
  "capabilities": ["${PRODUCTION_CAPABILITIES}"]
}
```

## Development Best Practices

### 1. Schema Validation
```typescript
// Validate against v1.5 schema
const schema = await fetch('https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json');
const validator = new JSONSchema(schema);
const isValid = validator.validate(agentManifest);
```

### 2. Character Limit Management
```typescript
// Validation helper functions
function validateName(name: string): boolean {
  return name.length > 0 && name.length <= 100;
}

function validateDescription(description: string): boolean {
  return description.length > 0 && description.length <= 1000;
}

function validateInstructions(instructions: string): boolean {
  return instructions.length > 0 && instructions.length <= 8000;
}
```

### 3. Capability Selection Strategy
- **Start Simple**: Begin with 1-2 core capabilities
- **Incremental Addition**: Add capabilities based on user feedback
- **Performance Testing**: Test each capability combination thoroughly
- **Enterprise Readiness**: Consider compliance and security implications

## Agents Playground Testing

### Local Testing Setup
```bash
# Start Agents Playground
npm install -g @microsoft/agents-playground
agents-playground start --manifest=./agent.json
```

### Testing Scenarios
1. **Capability Validation**: Test each declared capability
2. **Conversation Flow**: Validate conversation starters
3. **Error Handling**: Test invalid inputs and edge cases
4. **Performance**: Measure response times and reliability

## Deployment & Lifecycle Management

### 1. Development Lifecycle
```mermaid
graph LR
    A[TypeSpec Definition] --> B[JSON Compilation]
    B --> C[Local Testing]
    C --> D[Validation]
    D --> E[Staging Deployment]
    E --> F[Production Release]
```

### 2. Version Management
```json
{
  "name": "MyAgent v1.2.0",
  "description": "Production agent with enhanced capabilities",
  "version": "v1.5",
  "metadata": {
    "version": "1.2.0",
    "build": "20241208.1",
    "environment": "production"
  }
}
```

### 3. Environment Promotion
- **Development**: Full debugging, verbose logging
- **Staging**: Production-like testing, performance monitoring  
- **Production**: Optimized performance, minimal logging

## Advanced Features

### Behavior Overrides
```json
{
  "instructions": "You are a specialized financial analyst agent. Always provide disclaimers for financial advice.",
  "behavior_overrides": {
    "response_tone": "professional",
    "max_response_length": 2000,
    "citation_requirements": true
  }
}
```

### Localization Support
```json
{
  "name": {
    "en-US": "Financial Assistant",
    "es-ES": "Asistente Financiero",
    "fr-FR": "Assistant Financier"
  },
  "description": {
    "en-US": "Provides financial analysis and insights",
    "es-ES": "Proporciona análisis e insights financieros",
    "fr-FR": "Fournit des analyses et insights financiers"
  }
}
```

## Monitoring & Analytics

### Performance Metrics
- Response time per capability
- User engagement with conversation starters
- Error rates and failure patterns
- Capability utilization statistics

### Logging Strategy
```typescript
// Structured logging for agent interactions
const log = {
  timestamp: new Date().toISOString(),
  agentName: "MyAgent",
  version: "1.2.0",
  userId: "user123",
  capability: "WebSearch",
  responseTime: 1250,
  success: true
};
```

## Security & Compliance

### Data Privacy
- Implement proper data handling for sensitive information
- Ensure compliance with GDPR, CCPA, and organizational policies
- Use appropriate access controls for enterprise capabilities

### Security Considerations  
- Validate all inputs and outputs
- Implement rate limiting and abuse prevention
- Monitor for suspicious activity patterns
- Regular security audits and updates

## Troubleshooting

### Common Issues
1. **Schema Validation Errors**: Check character limits and required fields
2. **Capability Conflicts**: Verify capability combinations are supported
3. **Performance Issues**: Monitor response times and optimize instructions
4. **Deployment Failures**: Validate environment configuration and permissions

### Debug Tools
- TypeSpec compiler diagnostics
- Agents Playground debugging
- Microsoft 365 Agents Toolkit logs
- Schema validation utilities

---

name: declarative-agents-microsoft365
description: Comprehensive development guidelines for Microsoft 365 Copilot declarative agents with schema v1.5, TypeSpec integration, and Microsoft 365 Agents Toolkit workflows Triggers on: **.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json
triggers: "**.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json"
globs: "**.json, **.ts, **.tsp, **manifest.json, **agent.json, **declarative-agent.json"
---
# Microsoft 365 Declarative Agents Development Guidelines

## Overview

Microsoft 365 Copilot declarative agents are powerful custom AI assistants that extend Microsoft 365 Copilot with specialized capabilities, enterprise data access, and custom behaviors. These guidelines provide comprehensive development practices for creating production-ready agents using the latest v1.5 JSON schema specification with full Microsoft 365 Agents Toolkit integration.

## Schema Specification v1.5

### Core Properties

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
  "version": "v1.5",
  "name": "string (max 100 characters)",
  "description": "string (max 1000 characters)", 
  "instructions": "string (max 8000 characters)",
  "capabilities": ["array (max 5 items)"],
  "conversation_starters": ["array (max 4 items, optional)"]
}
```

### Character Limits & Constraints
- **Name**: Maximum 100 characters, required
- **Description**: Maximum 1000 characters, required  
- **Instructions**: Maximum 8000 characters, required
- **Capabilities**: Maximum 5 items, minimum 1 item
- **Conversation Starters**: Maximum 4 items, optional

## Available Capabilities

### Core Capabilities
1. **WebSearch**: Internet search and real-time information access
2. **OneDriveAndSharePoint**: File access, document search, content management
3. **GraphConnectors**: Enterprise data integration from third-party systems
4. **MicrosoftGraph**: Access to Microsoft 365 services and data

### Communication & Collaboration
5. **TeamsAndOutlook**: Teams chat, meetings, email integration
6. **CopilotForMicrosoft365**: Advanced Copilot features and workflows

### Business Applications
7. **PowerPlatform**: Power Apps, Power Automate, Power BI integration
8. **BusinessDataProcessing**: Advanced data analysis and processing
9. **WordAndExcel**: Document creation, editing, analysis
10. **EnterpriseApplications**: Third-party business system integration
11. **CustomConnectors**: Custom API and service integrations

## Microsoft 365 Agents Toolkit Integration

### VS Code Extension Setup
```bash
# Install Microsoft 365 Agents Toolkit
# Extension ID: teamsdevapp.ms-teams-vscode-extension
```

### TypeSpec Development Workflow

#### 1. Modern Agent Definition
```typespec
import "@typespec/json-schema";

using TypeSpec.JsonSchema;

@jsonSchema("/schemas/declarative-agent/v1.5/schema.json")
namespace DeclarativeAgent;

/** Microsoft 365 Declarative Agent */
model Agent {
  /** Schema version */
  @minLength(1)
  $schema: "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json";
  
  /** Agent version */
  version: "v1.5";
  
  /** Agent name (max 100 characters) */
  @maxLength(100)
  @minLength(1)
  name: string;
  
  /** Agent description (max 1000 characters) */
  @maxLength(1000)
  @minLength(1)  
  description: string;
  
  /** Agent instructions (max 8000 characters) */
  @maxLength(8000)
  @minLength(1)
  instructions: string;
  
  /** Agent capabilities (1-5 items) */
  @minItems(1)
  @maxItems(5)
  capabilities: AgentCapability[];
  
  /** Conversation starters (max 4 items) */
  @maxItems(4)
  conversation_starters?: ConversationStarter[];
}

/** Available agent capabilities */
union AgentCapability {
  "WebSearch",
  "OneDriveAndSharePoint", 
  "GraphConnectors",
  "MicrosoftGraph",
  "TeamsAndOutlook",
  "PowerPlatform",
  "BusinessDataProcessing",
  "WordAndExcel",
  "CopilotForMicrosoft365",
  "EnterpriseApplications",
  "CustomConnectors"
}

/** Conversation starter definition */
model ConversationStarter {
  /** Starter text (max 100 characters) */
  @maxLength(100)
  @minLength(1)
  text: string;
}
```

#### 2. Compilation to JSON
```bash
# Compile TypeSpec to JSON manifest
tsp compile agent.tsp --emit=@typespec/json-schema
```

### Environment Configuration

#### Development Environment
```json
{
  "name": "${DEV_AGENT_NAME}",
  "description": "Development version: ${AGENT_DESCRIPTION}",
  "instructions": "${AGENT_INSTRUCTIONS}",
  "capabilities": ["${REQUIRED_CAPABILITIES}"]
}
```

#### Production Environment
```json
{
  "name": "${PROD_AGENT_NAME}",
  "description": "${AGENT_DESCRIPTION}",
  "instructions": "${AGENT_INSTRUCTIONS}",
  "capabilities": ["${PRODUCTION_CAPABILITIES}"]
}
```

## Development Best Practices

### 1. Schema Validation
```typescript
// Validate against v1.5 schema
const schema = await fetch('https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json');
const validator = new JSONSchema(schema);
const isValid = validator.validate(agentManifest);
```

### 2. Character Limit Management
```typescript
// Validation helper functions
function validateName(name: string): boolean {
  return name.length > 0 && name.length <= 100;
}

function validateDescription(description: string): boolean {
  return description.length > 0 && description.length <= 1000;
}

function validateInstructions(instructions: string): boolean {
  return instructions.length > 0 && instructions.length <= 8000;
}
```

### 3. Capability Selection Strategy
- **Start Simple**: Begin with 1-2 core capabilities
- **Incremental Addition**: Add capabilities based on user feedback
- **Performance Testing**: Test each capability combination thoroughly
- **Enterprise Readiness**: Consider compliance and security implications

## Agents Playground Testing

### Local Testing Setup
```bash
# Start Agents Playground
npm install -g @microsoft/agents-playground
agents-playground start --manifest=./agent.json
```

### Testing Scenarios
1. **Capability Validation**: Test each declared capability
2. **Conversation Flow**: Validate conversation starters
3. **Error Handling**: Test invalid inputs and edge cases
4. **Performance**: Measure response times and reliability

## Deployment & Lifecycle Management

### 1. Development Lifecycle
```mermaid
graph LR
    A[TypeSpec Definition] --> B[JSON Compilation]
    B --> C[Local Testing]
    C --> D[Validation]
    D --> E[Staging Deployment]
    E --> F[Production Release]
```

### 2. Version Management
```json
{
  "name": "MyAgent v1.2.0",
  "description": "Production agent with enhanced capabilities",
  "version": "v1.5",
  "metadata": {
    "version": "1.2.0",
    "build": "20241208.1",
    "environment": "production"
  }
}
```

### 3. Environment Promotion
- **Development**: Full debugging, verbose logging
- **Staging**: Production-like testing, performance monitoring  
- **Production**: Optimized performance, minimal logging

## Advanced Features

### Behavior Overrides
```json
{
  "instructions": "You are a specialized financial analyst agent. Always provide disclaimers for financial advice.",
  "behavior_overrides": {
    "response_tone": "professional",
    "max_response_length": 2000,
    "citation_requirements": true
  }
}
```

### Localization Support
```json
{
  "name": {
    "en-US": "Financial Assistant",
    "es-ES": "Asistente Financiero",
    "fr-FR": "Assistant Financier"
  },
  "description": {
    "en-US": "Provides financial analysis and insights",
    "es-ES": "Proporciona análisis e insights financieros",
    "fr-FR": "Fournit des analyses et insights financiers"
  }
}
```

## Monitoring & Analytics

### Performance Metrics
- Response time per capability
- User engagement with conversation starters
- Error rates and failure patterns
- Capability utilization statistics

### Logging Strategy
```typescript
// Structured logging for agent interactions
const log = {
  timestamp: new Date().toISOString(),
  agentName: "MyAgent",
  version: "1.2.0",
  userId: "user123",
  capability: "WebSearch",
  responseTime: 1250,
  success: true
};
```

## Security & Compliance

### Data Privacy
- Implement proper data handling for sensitive information
- Ensure compliance with GDPR, CCPA, and organizational policies
- Use appropriate access controls for enterprise capabilities

### Security Considerations  
- Validate all inputs and outputs
- Implement rate limiting and abuse prevention
- Monitor for suspicious activity patterns
- Regular security audits and updates

## Troubleshooting

### Common Issues
1. **Schema Validation Errors**: Check character limits and required fields
2. **Capability Conflicts**: Verify capability combinations are supported
3. **Performance Issues**: Monitor response times and optimize instructions
4. **Deployment Failures**: Validate environment configuration and permissions

### Debug Tools
- TypeSpec compiler diagnostics
- Agents Playground debugging
- Microsoft 365 Agents Toolkit logs
- Schema validation utilities

This comprehensive guide ensures robust, scalable, and maintainable Microsoft 365 Copilot declarative agents with full TypeSpec and Microsoft 365 Agents Toolkit integration.

Related Skills

agentsmd-claudemd-generator

from diegosouzapw/awesome-omni-skill

Generate AGENTS.md and CLAUDE.md files for a repository. AGENTS.md provides cross-tool agent instructions (supported by Claude Code, Cursor, Windsurf, Zed, Codex, and others). CLAUDE.md adds Claude-specific configuration and references AGENTS.md via @import. Use when a repo needs agent onboarding or when starting a new project.

agents-md-guidelines

from diegosouzapw/awesome-omni-skill

Guidelines for writing small, stable AGENTS.md files. Use when creating, refactoring, or reviewing AGENTS.md.

agents-md-generator

from diegosouzapw/awesome-omni-skill

Generate comprehensive agents.md files for Builder.io Fusion projects. Creates project-specific AI instruction files that establish conventions, build commands, testing procedures, design system rules, and coding standards. Use when setting up a new project, onboarding a repository to AI-assisted development, or improving AI code generation quality.

developing-claude-agent-sdk-agents

from diegosouzapw/awesome-omni-skill

Build AI agents with the Claude Agent SDK (TypeScript/Python). Covers creating agents, custom tools, hooks, subagents, MCP integration, permissions, sessions, and deployment. Use when building, reviewing, debugging, or deploying SDK-based agents. Invoke PROACTIVELY when user mentions Agent SDK, claude-agent-sdk, ClaudeSDKClient, query(), or building autonomous agents.

deepagents-filesystem

from diegosouzapw/awesome-omni-skill

Using FilesystemMiddleware with virtual filesystems, backends (State, Store, Filesystem, Composite), and context management for Deep Agents.

autogpt-agents

from diegosouzapw/awesome-omni-skill

Autonomous AI agent platform for building and deploying continuous agents. Use when creating visual workflow agents, deploying persistent autonomous agents, or building complex multi-step AI automation systems.

Analyzing AgentScope Library

from diegosouzapw/awesome-omni-skill

This skill provides a way to retrieve information from the AgentScope library for analysis and decision-making.

agentstack-server-debugging

from diegosouzapw/awesome-omni-skill

Instructions for debugging agentstack-server during development

zig-agents

from diegosouzapw/awesome-omni-skill

Patterns and best practices for building AI agents in Zig. Covers tool systems, context management, LLM providers, streaming responses, and session persistence. Use when implementing agent functionality.

writing-agents

from diegosouzapw/awesome-omni-skill

Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool

voice-agents

from diegosouzapw/awesome-omni-skill

Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis, it's achieving natural conversation flo...

vat-example-cat-agents

from diegosouzapw/awesome-omni-skill

Comprehensive orchestration guide for Claude Code using the vat-example-cat-agents toolkit