首页
teams-app-developer
microsoft/skills
使用 ATK CLI 构建、测试并部署适用于 Teams 和 Copilot 的 Microsoft 365 应用及智能体，涵盖项目创建、本地测试、云部署、故障排除以及 Slack 到 Teams 迁移等子技能。
...展开全部
0
更新时间 2026-09-16
# copilot
# azure
# microsoft 365
# teams
# agents playground
# atk cli
# devtunnel
# slack migration
Microsoft 365 代理工具包技能
使用 ATK CLI 构建 Microsoft 365 代理和 Teams 应用。
AI 行为准则
测试策略： 优先推荐代理游乐场（Agents Playground）（速度更快，无需 M365）。仅当用户明确要求时才使用 Teams 工作流。
环境变量： 绝不要硬编码密钥或编造占位符值。始终向用户询问真实值。
错误处理： 仔细阅读错误消息。检查
env/.env.local、.localConfigs和atk auth list。常见陷阱：AADSTS7000229→aadApp/create在 YAML 中缺少generateServicePrincipal: true— 添加它并重新配置.localConfigs中缺少TENANT_ID→ SDK 使用错误的令牌颁发机构 → Bot Connector 返回 401- 修复身份验证后 401 仍然存在 → devtunnel URL 可能被列入黑名单 — 创建一个新的隧道
- 请参阅 troubleshoot/troubleshoot.md 以获取完整的诊断步骤
长时间运行的命令 — 等待完成：
atk new、atk provision、atk deploy可能需要几分钟- 始终在运行下一步之前等待完成（超时 120000ms+）
本地服务启动 — 挂起终端（预期行为）：
npm run dev、npm start、python app.py、devtunnel host等命令会挂起 — 进程将无限期运行- 始终作为后台进程运行（
isBackground=true） — 对这些命令绝不要使用isBackground=false - 不要等待它“完成” — 通过检查输出中的“listening on port”或隧道 URL 来验证启动
- 如果出现错误，读取日志、诊断、修复、重启
- 使用新终端启动代理游乐场或打开 Teams 侧载 URL
监控应用日志： 定期检查后台终端输出以查找运行时错误。如果应用崩溃，读取错误，修复根本原因，然后重启。
遥测标记： 在运行任何
atkCLI 命令之前，设置会话环境变量，以便所有 CLI 调用都标记为技能发起：export ATK_CLI_SKILL=true在会话开始时运行一次。同一终端中的后续
atk命令将继承该设置。
ATK CLI 设置
atk --version # 必须 > 1.1.5-beta
如果未找到 ATK 或版本过旧：
npm i -g @microsoft/m365agentstoolkit-cli@beta
CLI 全局选项
| 选项 | 含义 | 建议 |
|---|---|---|
| `-i` | 交互模式 | 在自动化中始终使用 `-i false` 以避免挂起 |
| `-f` | 项目文件夹 | 默认为当前目录，用于指定自定义文件夹时。在生成新项目时，这是项目文件夹将创建在其下的父文件夹。 |
| `-h` | 命令帮助 | 使用 `atk |
子技能
| 子技能 | 使用场景 | 参考 |
|---|---|---|
| **create-project** | 从模板生成新项目，选择模板，`atk new` | create-project/create-project.md |
| **test-playground** | 使用代理游乐场进行本地测试，`agentsplayground`，快速测试 | test-playground/test-playground.md |
| **test-teams** | 在 Teams 上运行，devtunnel，侧载，Teams 测试，在 Copilot 中测试 | test-teams/test-teams.md |
| **provision-deploy** | 配置 Azure 资源，部署到云，`atk provision`，`atk deploy` | provision-deploy/provision-deploy.md |
| **troubleshoot** | 修复错误、401、端口冲突、YAML 错误、过时的机器人 | troubleshoot/troubleshoot.md |
| **slack-to-teams** | 将 Slack 机器人迁移到 Teams，跨平台桥接，Block Kit 到自适应卡片 | slack-to-teams/SKILL.md |
强制要求： 在执行任何工作流之前，阅读相应的子技能文档。
共享参考
- manifest-and-yaml.md — 项目文件、YAML 配置、环境变量、.localConfigs 流程
- commands.md — ATK CLI 命令：package、validate、share、collaborate
- templates.md — 完整的模板目录及语言支持
- experts/ — 100 多个微专家文件：Teams SDK、Slack SDK、跨平台桥接、部署、AI 模型、安全、语言转换
- docs/ — 平台比较指南：UI、消息传递、身份、基础设施、功能差距
工作流链
将用户意图匹配到最小的有效工作流。
| 用户意图 | 工作流（按顺序阅读） |
|---|---|
| 从头构建新应用 | create-project → test-playground |
| 在本地测试现有项目 | test-playground（推荐）或 test-teams |
| 部署到 Azure | provision-deploy |
| 修复损坏的机器人 | troubleshoot → 重新测试 |
| 将 Slack 机器人迁移到 Teams | slack-to-teams |
强制要求： 在执行任何 slack-to-teams 工作流之前，先阅读 slack-to-teams/SKILL.md。该子技能包含一个路由专家系统，拥有 100 多个微专家文件，用于跨平台机器人开发。
ATK 项目上下文解析
仅在缺失时解析配置值。如果会话中已知某个值，请重用该值。
步骤 1：检测 ATK 项目
如果当前文件夹中存在 m365agentstoolkit*.yml，则将其视为 ATK 项目并解析配置。
步骤 2：解析通用配置
解析 m365agentstoolkit*.yml 中引用的变量。常见变量：AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT_NAME
步骤 3：收集缺失的值
如果缺少必需的值，仅向用户询问缺失的值。
有关完整的配置文件详细信息，请参阅 manifest-and-yaml.md。
在 GitHub 上查看
---
name: teams-app-developer
description: Builds, tests, and deploys Microsoft 365 apps and agents for Teams and Copilot using the ATK CLI, with sub-skills for project creation, local testing, cloud deployment, troubleshooting, and Slack-to-Teams migration.
---
# Microsoft 365 Agents Toolkit Skill
Build Microsoft 365 agents and Teams apps using the ATK CLI.
## AI Behavior Guidelines
1. **Testing Strategy:** Recommend Agents Playground first (faster, no M365 needed). Use Teams workflow only if user explicitly requests it.
2. **Environment Variables:** NEVER hardcode secrets or make up placeholder values. Always ask users for real values.
3. **Error Handling:** Read error messages carefully. Check `env/.env.local`, `.localConfigs`, and `atk auth list`. Common pitfalls:
- **`AADSTS7000229`** → `aadApp/create` missing `generateServicePrincipal: true` in YAML — add it and re-provision
- **Missing `TENANT_ID`** in `.localConfigs` → SDK uses wrong token authority → 401 from Bot Connector
- **401 persists after auth fix** → devtunnel URL may be blacklisted — create a fresh tunnel
- See [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md) for full diagnostic steps
4. **Long-Running Commands — WAIT for completion:**
- `atk new`, `atk provision`, `atk deploy` can take several minutes
- Always wait for completion before running the next step (timeout 120000ms+)
5. **Local Service Startup — Hangs terminal (expected):**
- `npm run dev`, `npm start`, `python app.py`, `devtunnel host`, etc. will hang — the process keeps running indefinitely
- ALWAYS run as a background process (`isBackground=true`) — NEVER use `isBackground=false` for these commands
- Do NOT wait for it to "finish" — verify startup by checking output for "listening on port" or tunnel URL
- If errors appear, read logs, diagnose, fix, restart
- Use a **NEW terminal** to launch Agents Playground or open Teams sideloading URL
6. **Monitor App Logs:** Periodically check background terminal output for runtime errors. If the app crashes, read the error, fix the root cause, and restart.
7. **Telemetry Tagging:** Before running any `atk` CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:
```bash
export ATK_CLI_SKILL=true
```
Run this once at the start of the session. All subsequent `atk` commands in the same terminal will inherit it.
## ATK CLI Setup
```bash
atk --version # Must be > 1.1.5-beta
```
If ATK is not found or version is too old:
```bash
npm i -g @microsoft/m365agentstoolkit-cli@beta
```
## CLI Global Options
| Option | Meaning | Recommendation |
| ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-i` | Interactive mode | Always use `-i false` in automation to avoid hanging |
| `-f` | Project folder | Default to be current directory, used when specifying a custom folder. When scaffolding a new project, this is the parent folder where the project folder will be created under. |
| `-h` | Command help | Use `atk <command> -h` for quick syntax checks |
## Sub-Skills
| Sub-Skill | When to Use | Reference |
| -------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **create-project** | Scaffold new project from template, choose template, `atk new` | [create-project/create-project.md](create-project/create-project.md) |
| **test-playground** | Test locally with Agents Playground, `agentsplayground`, quick testing | [test-playground/test-playground.md](test-playground/test-playground.md) |
| **test-teams** | Run on Teams, devtunnel, sideload, Teams testing, test in Copilot | [test-teams/test-teams.md](test-teams/test-teams.md) |
| **provision-deploy** | Provision Azure resources, deploy to cloud, `atk provision`, `atk deploy` | [provision-deploy/provision-deploy.md](provision-deploy/provision-deploy.md) |
| **troubleshoot** | Fix errors, 401, port conflicts, YAML errors, stale bots | [troubleshoot/troubleshoot.md](troubleshoot/troubleshoot.md) |
| **slack-to-teams** | Migrate Slack bot to Teams, cross-platform bridging, Block Kit to Adaptive Cards | [slack-to-teams/SKILL.md](slack-to-teams/SKILL.md) |
> **MANDATORY:** Before executing any workflow, read the corresponding sub-skill document.
## Shared References
- [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) — Project files, YAML config, env vars, .localConfigs flow
- [commands.md](toolkit/commands.md) — ATK CLI commands: package, validate, share, collaborate
- [templates.md](toolkit/templates.md) — Complete template catalog with language support
- [experts/](experts/index.md) — 100+ micro-expert files: Teams SDK, Slack SDK, cross-platform bridging, deploy, AI models, security, language conversion
- [docs/](docs/README.md) — Platform comparison guides: UI, messaging, identity, infrastructure, feature gaps
## Workflow Chains
Match user intent to the smallest valid workflow.
| User Intent | Workflow (read in order) |
| ----------------------------- | ------------------------------------------- |
| Build new app from scratch | create-project → test-playground |
| Test existing project locally | test-playground (recommended) or test-teams |
| Deploy to Azure | provision-deploy |
| Fix broken bot | troubleshoot → re-test |
| Migrate Slack bot to Teams | slack-to-teams |
> **MANDATORY:** Before executing any slack-to-teams workflow, read [slack-to-teams/SKILL.md](slack-to-teams/SKILL.md) first. The sub-skill contains a routed expert system with 100+ micro-expert files for cross-platform bot development.
## ATK Project Context Resolution
Resolve config values only when missing. If a value is already known in the session, reuse it.
### Step 1: Detect ATK Project
If `m365agentstoolkit*.yml` exists in the current folder, treat it as an ATK project and parse configuration.
### Step 2: Resolve Common Configuration
Resolve variables referenced in `m365agentstoolkit*.yml`. Common variables:
AZURE_OPENAI_API_KEY
AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_DEPLOYMENT_NAME
### Step 3: Collect Missing Values
If required values are missing, ask the user for only the missing ones.
Refer to [manifest-and-yaml.md](toolkit/manifest-and-yaml.md) for full config-file details.
所有文件
147 个文件
docs/README.md
2.8k
查看
docs/feature-gaps.md
46.3k
查看
docs/workflows.md
14.4k
查看
experts/README.md
8.6k
查看
experts/builder.md
11.1k
查看
experts/fallback.md
2.1k
查看
experts/index.md
18.9k
查看
toolkit/README.md
4.2k
查看
toolkit/commands.md
2.6k
查看
toolkit/environments.md
12.6k
查看
toolkit/lifecycle-cli.md
17.6k
查看
toolkit/publish.md
9.3k
查看
toolkit/templates.md
6.7k
查看
安装 teams-app-developer
将技能文件下载并解压至你的 .claude/skills/ 目录。
下载ZIP克隆仓库并复制技能文件到您的项目中。
git clone https://github.com/microsoft/skills/tree/main/.github/plugins/microsoft-365-agents-toolkit/skills/teams-app-developer # Copy SKILL.md to your .claude/skills/ directory
复制
快速设置:
将技能文件夹复制到 .claude/skills/ 目录。Claude 将自动检测并使用该技能。
相关技能
base44-cli
更新时间 2026-06-29
klingai-upgrade-migration
更新时间 2026-07-03
Railway CLI Management
更新时间 2026-07-02
Verification & Quality Assurance
更新时间 2026-06-29
