Skip to content

feat: use sub-skills structure and add related knowledge #15587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Alive-Fish wants to merge 1 commit into
base: dev
Choose a base branch
from
Draft

feat: use sub-skills structure and add related knowledge #15587

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
333 changes: 61 additions & 272 deletions packages/vscode-extension/skills/microsoft-365-agents-toolkit/SKILL.md
View file
Open in desktop

Large diffs are not rendered by default.

89 changes: 89 additions & 0 deletions ...-extension/skills/microsoft-365-agents-toolkit/create-project/create-project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Create Project

Scaffold a new Microsoft 365 agent or Teams app from an ATK template.

## Template Selection Guide

| User Wants | Capability |
|------------|------------|
| Extend M365 Copilot with custom instructions | `declarative-agent` |
| Declarative Agent with new API | `declarative-agent-action` |
| Declarative Agent with new API (Bearer Token) | `declarative-agent-action-bearer` |
| Declarative Agent with new API (OAuth) | `declarative-agent-action-oauth` |
| Declarative Agent with existing OpenAPI spec | `declarative-agent-action-from-existing-api` |
| Connect MCP Server to Copilot | `declarative-agent-with-action-from-mcp` |
| Declarative Agent with Copilot Connector | `declarative-agent-with-graph-connector` |
| Declarative Agent for MetaOS | `declarative-agent-meta-os-new-project` |
| Declarative Agent from TypeSpec | `declarative-agent-typespec` |
| Agent with custom LLM (Azure OpenAI, etc.) | `basic-custom-engine-agent` |
| Weather forecast agent | `weather-agent` |
| Agent using Azure AI Foundry | `foundry-agent-to-m365` |
| Teams chatbot with AI | `teams-agent` |
| Teams bot with RAG/knowledge base | `teams-agent-rag-customize` |
| Teams Agent with Azure AI Search | `teams-agent-rag-azure-ai-search` |
| Teams Agent with Custom API | `teams-agent-rag-custom-api` |
| Teams Collaborator Agent | `teams-collaborator-agent` |
| Simple Teams echo bot | `bot` |
| Teams tab app | `tab` |
| Teams message extension | `message-extension` |
| Copilot Connector | `copilot-connector` |

See [../references/templates.md](../references/templates.md) for the complete template catalog with language support and descriptions.

## Creating Projects

**Default project folder:** `~/AgentsToolkitProjects`

```bash
# Declarative Agent (no backend, no -l flag needed)
atk new -c declarative-agent -n my-agent -f ~/AgentsToolkitProjects -i false

# Declarative Agent with new API
atk new -c declarative-agent-action -l typescript -n my-api-agent -f ~/AgentsToolkitProjects -i false

# Declarative Agent with existing OpenAPI spec (requires -a and -o with operation IDs)
atk new -c declarative-agent-action-from-existing-api -n my-agent -a <openapi-spec-url-or-path> -o "GET /repairs" -o "POST /repairs" -f ~/AgentsToolkitProjects -i false

# Custom Engine Agent
atk new -c basic-custom-engine-agent -l typescript -n my-cea -f ~/AgentsToolkitProjects -i false

# Teams Agent with RAG
atk new -c teams-agent-rag-customize -l typescript -n my-rag-agent -f ~/AgentsToolkitProjects -i false
```

## Creating from Samples

```bash
atk new sample <sample-id>
```

| Sample | Sample ID (`atk new sample <sample-id>`) | Tags |
| ------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| Langchain Agent with Agent365 SDK in NodeJS | `agent365-langchain-nodejs` | Agent365, TS |
| Agent Framework Agent with Agent365 SDK in Python | `agent365-agentframework-python` | Agent365, Python |
| OpenAI Agent with Agent365 SDK in Python | `agent365-openai-python` | Agent365, Python |
| Claude Agent with Agent365 SDK in NodeJS | `agent365-claude-nodejs` | Agent365, TS |
| Tab App with Azure Backend | `hello-world-tab-with-backend` | Tab, TS, Azure Functions, Dev Proxy |
| Bot App with SSO Enabled | `bot-sso` | Bot, TS, Adaptive Cards, SSO |
| Team Central Dashboard | `team-central-dashboard` | Tab, TS, Azure Functions, SSO |
| Copilot connector App | `copilot-connector-app` | Tab, Azure Functions, TS, SSO, Copilot connector |
| Teams Conversation Bot using Python | `bot-conversation-python` | Python, Bot, Bot Framework |
| Teams Messaging Extensions Search using Python | `msgext-search-python` | Python, Message extension, Bot Framework |
| Travel Agent | `travel-agent` | C#, Custom Engine Agent, M365 Copilot Retrieval API, Agents SDK, Agent Framework |
| Coffee Agent | `coffee-agent` | TS, Custom Engine Agent, Adaptive Cards, Microsoft Teams SDK |
| Data Analyst Agent v2 | `data-analyst-agent-v2` | TS, Custom Engine Agent, Data Visualization, Adaptive Cards, LLM SQL, Microsoft Teams SDK |

List all samples with `atk list samples`.

## Notes

- `declarative-agent` does NOT require `-l` language flag
- `declarative-agent-action-from-existing-api` requires `-a` (OpenAPI spec) and `-o` (operation IDs like `"GET /path"`)
- Always use `-i false` for non-interactive scripted creation
- `atk new` can take several minutes — wait for completion (timeout 120000ms+)

## After Scaffolding

Once the project is created:
- To test locally → see [../test-playground/test-playground.md](../test-playground/test-playground.md)
- To understand project files → see [../references/manifest-and-yaml.md](../references/manifest-and-yaml.md)
45 changes: 45 additions & 0 deletions packages/vscode-extension/skills/microsoft-365-agents-toolkit/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Slack vs Teams: Platform Differences & Bridging Strategies

A practical guide for developers adding cross-platform support to an existing bot. Each document covers a category of differences, explains why they matter, and provides concrete mitigation strategies with effort estimates.

## Documents

| Document | What It Covers |
|---|---|
| [**Feature Gaps**](feature-gaps.md) | **Complete inventory of every RED and YELLOW gap with mitigations in both directions** |
| [Messaging & Commands](messaging-and-commands.md) | Messages, slash commands, events, threading, @mentions |
| [UI Components](ui-components.md) | Block Kit vs Adaptive Cards, modals vs dialogs, App Home vs personal tabs |
| [Interactive Responses](interactive-responses.md) | Ephemeral messages, button actions, message updates, confirmation dialogs |
| [Identity & Auth](identity-and-auth.md) | User IDs, OAuth, signing/verification, tokens |
| [Files & Links](files-and-links.md) | File upload/download, link unfurling/previews |
| [Middleware & Handler Patterns](middleware-and-handlers.md) | Middleware chains, ack(), handler registration, error handling |
| [Advanced Features](advanced-features.md) | Scheduling, workflows, shortcuts, channel ops, reactions, distribution |
| [Infrastructure](infrastructure.md) | Transport, compute, storage, secrets, observability |
| [**Eval Harness**](../evals/README.md) | Automated testing for expert routing, completeness, and code patterns |

## Eval Harness

The [`evals/`](../evals/) directory contains an automated test harness for the expert system. It validates three dimensions:

- **Routing** — 51 test cases across all 7 domains verify queries route to the correct domain, clusters, and expert files
- **Completeness** — 9 test cases check experts cover all required concepts for their domain
- **Patterns** — 294 TypeScript code blocks across all experts are compiled in-memory to catch syntax errors

Pattern evals are fully deterministic (no API key needed). Routing and completeness evals use an LLM judge (OpenAI, Anthropic, or Azure OpenAI). See [`evals/README.md`](../evals/README.md) for setup and usage.

## How to Read These Docs

Each difference follows this format:

- **What's different** — the concrete behavioral gap
- **Impact** — what breaks or degrades if you ignore it
- **Mitigation** — one or more strategies ranked by effort and fidelity
- **Effort** — rough hours to implement

### Difficulty Ratings

| Rating | Meaning |
|---|---|
| GREEN | Direct mapping exists. Mechanical conversion, minimal design decisions. |
| YELLOW | Mapping exists but requires design decisions or trade-offs. |
| RED | Platform gap — no equivalent exists. Requires redesign or custom workaround. |
149 changes: 149 additions & 0 deletions .../vscode-extension/skills/microsoft-365-agents-toolkit/docs/advanced-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# Advanced Features

## Scheduled Messages

| Aspect | Slack | Teams |
|---|---|---|
| Native API | `chat.scheduleMessage()` | **No equivalent** |
| Cancel scheduled | `chat.deleteScheduledMessage()` | N/A |
| Reminders | `reminders.add()` | **No equivalent** |

**Rating:** RED (Slack → Teams), GREEN (Teams → Slack).

### Mitigation Strategies (Slack → Teams)

| Strategy | How | Effort |
|---|---|---|
| **Azure Functions timer + Cosmos DB (Recommended)** | Store scheduled message in Cosmos DB. Azure Functions timer trigger polls and sends via proactive messaging. | 16–24 hrs |
| **Azure Queue visibility timeout** | Set visibility timeout to delay message processing. 7-day maximum. | 8–12 hrs |
| **Azure Service Bus scheduled messages** | Best for high-volume exact-time delivery. | 12–16 hrs |
| **Power Automate** | Offload to Power Automate flows with "Delay until" action. Requires license. | 8–12 hrs |
| **In-process timer (dev only)** | `setTimeout` / `node-cron`. Not durable — lost on restart. | 2–4 hrs |

### Reverse Direction (Teams → Slack)

Use `chat.scheduleMessage()` and `reminders.add()` directly — native APIs.

---

## Emoji Reactions

| Aspect | Slack | Teams |
|---|---|---|
| Event | `reaction_added` / `reaction_removed` | `messageReaction` |
| Reaction types | Unlimited custom emoji | **6 fixed reactions only**: like, heart, laugh, surprised, sad, angry |
| Workflow use | Common to use reactions as workflow signals (e.g., `:white_check_mark:` = approved) | Not viable — too few options |

**Rating:** RED (Slack → Teams) if reactions are used as workflow signals.

### Mitigation (Slack → Teams)

| Strategy | How | Effort |
|---|---|---|
| **Adaptive Card buttons (Recommended)** | Replace reaction-based workflows with `Action.Submit` buttons on cards (e.g., "Approve" / "Reject"). Better for audit trails. | 4–8 hrs |
| **Map to 6 fixed reactions** | Map your most important reactions to like/heart/laugh/surprised/sad/angry. Lossy — only works if you use ≤6 reactions. | 2–4 hrs |

### Reverse Direction (Teams → Slack)

Slack supports unlimited custom emoji reactions — direct mapping.

---

## Shortcuts / Message Extensions

| Aspect | Slack | Teams |
|---|---|---|
| Global shortcut | `app.shortcut("callback_id")` | Compose extension with `context: ["compose", "commandBox"]` |
| Message shortcut | `app.shortcut("callback_id")` (type: `message_shortcut`) | Action extension with `context: ["message"]` |
| Fire-and-forget | Supported (ack + background work) | **Not supported** — must open task module |
| Manifest config | Shortcut in app settings | `composeExtensions[].commands[]` |
| Message context | `shortcut.message` | `activity.value.messagePayload` |

**Rating:** YELLOW — functional equivalents exist but UX differs.

### Key Difference

Slack shortcuts can run background actions without showing UI (ack + do work). Teams compose/action extensions always open a task module — there's no fire-and-forget pattern. Use a "minimal dismiss" pattern: return a tiny "Done" card that auto-closes.

### Mitigation (Slack → Teams)

| Strategy | How | Effort |
|---|---|---|
| **Compose extension (Recommended)** | `composeExtensions` with `commandBox` context. Opens task module. | 8–12 hrs |
| **Minimal-dismiss pattern** | Task module returns tiny "Done" card for fire-and-forget actions. | 4–8 hrs |
| **Bot command replacement** | Replace shortcut with typed command. Simpler but less discoverable. | 2–4 hrs |

---

## Channel Operations

| Aspect | Slack | Teams |
|---|---|---|
| Create channel | `conversations.create()` | Graph `POST /teams/{team-id}/channels` |
| Archive channel | `conversations.archive()` | **No equivalent** — Teams can only archive entire Teams |
| Set topic | `conversations.setTopic()` | Graph `PATCH /channels/{id}` with `description` |
| Invite member | `conversations.invite()` | Graph `POST /channels/{id}/members` (one call per member) |
| Remove member | `conversations.kick()` | Graph `DELETE /channels/{id}/members/{membership-id}` (must resolve membership ID first) |
| Channel namespace | Flat (channel ID is globally unique) | Team-scoped (need `team-id` + `channel-id`) |
| Channel name limits | 80 chars, most characters allowed | 50 chars, no special characters |

**Rating:** GREEN for create/topic/invite, YELLOW for remove (membership ID resolution), RED for archive.

### Archive Mitigation (Slack → Teams)

| Strategy | How | Effort |
|---|---|---|
| **Rename with [ARCHIVED] prefix (Recommended)** | Rename channel, update description. Cosmetic but non-destructive. | 4–8 hrs |
| **Rename + remove all members** | Stronger enforcement but destructive — members must be re-invited to undo. | 8–12 hrs |
| **Team-level archive** | Archive entire Team. Only works if channel is in a dedicated Team. | 2–4 hrs |

---

## Workflows / Automation

| Aspect | Slack | Teams |
|---|---|---|
| Platform | Workflow Builder (free) | Power Automate (licensed for premium connectors) |
| Bot integration | `workflow_step_execute` event | Custom connectors or bot-driven orchestration |
| Triggers | Channel message, emoji reaction, scheduled, webhook | Same + Approvals connector, Planner, SharePoint |
| Migration tool | N/A | **None** — manual rebuild required |

**Rating:** YELLOW — functional equivalent exists but different platform, possible licensing.

### Mitigation Strategies

| Strategy | How | Effort |
|---|---|---|
| **Bot-driven orchestration (Recommended)** | Keep workflow logic in the bot. State machine + Adaptive Card buttons + persistent storage. No license dependency. | 16–40 hrs |
| **Power Automate rebuild** | Rebuild in Power Automate. Custom steps need Premium license. | 24–80 hrs |
| **Hybrid** | Simple flows → Power Automate, complex → bot-driven. | Varies |
| **Teams Workflows app** | Simplified UI for basic automations (free). Limited to simple scenarios. | 4–8 hrs |

---

## App Distribution

| Aspect | Slack | Teams |
|---|---|---|
| Directory listing | Slack App Directory (api.slack.com) | Teams App Store via Partner Center |
| Review time | Hours to days | 1–2 weeks |
| Org-level install | Workspace admin approval | Teams Admin Center tenant-wide deployment |
| Dev install | Direct install via OAuth URL | Sideloading (ZIP with manifest + icons) |
| Required assets | App icon | 192x192 full-color icon + 32x32 monochrome outline |
| Multi-tenant | Per-workspace tokens via `InstallationStore` | `signInAudience: "AzureADMultipleOrgs"` in Azure AD |

**Rating:** YELLOW — both have distribution mechanisms but packaging and review differ.

### Sideloading (Dev/Test)

Teams sideloading requires:
1. `manifest.json` (schema v1.19+)
2. `color.png` (192x192)
3. `outline.png` (32x32 monochrome)
4. ZIP all three files
5. Upload via Teams client → Apps → Manage your apps → Upload
6. Note: Sideloading may be disabled by admin — check tenant settings

### Reverse Direction (Teams → Slack)

Submit to Slack App Directory via api.slack.com. Implement `InstallProvider` for OAuth install flow. Shorter review cycle.
Loading
Loading