Lar
teams-app-developer
microsoft/skills
Cria, testa e implanta aplicativos e agentes do Microsoft 365 para Teams e Copilot por meio do CLI do ATK, com habilidades secundárias para criação de projetos, testes locais, implantação em nuvem, solução de problemas e migração do Slack para o Teams.
...Expandir tudoFerramenta de Habilidades do Kit de Ferramentas de Agentes do Microsoft 365
Crie agentes do Microsoft 365 e aplicativos do Teams usando o CLI do ATK.
Diretrizes de Comportamento de IA
Estratégia de Teste: Recomende o Agents Playground primeiro (mais rápido, sem necessidade do M365). Use o fluxo de trabalho do Teams apenas se o usuário solicitar explicitamente.
Variáveis de Ambiente: NUNCA codifique segredos ou crie valores de espaço reservado. Sempre solicite aos usuários os valores reais.
Tratamento de Erros: Leia as mensagens de erro cuidadosamente. Verifique
env/.env.local,.localConfigseatk auth list. Armadilhas comuns:AADSTS7000229→aadApp/createfaltagenerateServicePrincipal: trueno YAML — adicione-o e reprovisione- Falta
TENANT_IDem.localConfigs→ o SDK usa autoridade de token incorreta → 401 do Bot Connector - 401 persiste após correção de autenticação → a URL do devtunnel pode estar na lista negra — crie um túnel novo
- Consulte troubleshoot/troubleshoot.md para etapas completas de diagnóstico
Comandos de Longa Duração — AGUARDE a conclusão:
atk new,atk provision,atk deploypodem levar vários minutos- Sempre aguarde a conclusão antes de executar a próxima etapa (tempo limite de 120000ms+)
Início do Serviço Local — Trava o terminal (esperado):
npm run dev,npm start,python app.py,devtunnel host, etc. travarão — o processo continua executando indefinidamente- SEMPRE execute como um processo em segundo plano (
isBackground=true) — NUNCA useisBackground=falsepara esses comandos - NÃO aguarde que termine — verifique o início verificando a saída por "listening on port" ou URL do túnel
- Se aparecerem erros, leia os logs, diagnostique, corrija e reinicie
- Use um NOVO terminal para iniciar o Agents Playground ou abrir a URL de sideloading do Teams
Monitorar Logs do Aplicativo: Verifique periodicamente a saída do terminal em segundo plano em busca de erros de tempo de execução. Se o aplicativo falhar, leia o erro, corrija a causa raiz e reinicie.
Marcação de Telemetria: Antes de executar qualquer comando do CLI
atk, defina a variável de ambiente da sessão para que todas as invocações do CLI sejam marcadas como iniciadas pela habilidade:export ATK_CLI_SKILL=trueExecute isso uma vez no início da sessão. Todos os comandos
atksubsequentes no mesmo terminal herdarão essa configuração.
Configuração do CLI do ATK
atk --version # Deve ser > 1.1.5-beta
Se o ATK não for encontrado ou a versão estiver muito antiga:
npm i -g @microsoft/m365agentstoolkit-cli@beta
Opções Globais do CLI
| Opção | Significado | Recomendação |
|---|---|---|
| `-i` | Modo interativo | Sempre use `-i false` na automação para evitar travamentos |
| `-f` | Pasta do projeto | O padrão é o diretório atual, usado ao especificar uma pasta personalizada. Ao criar um novo projeto, esta é a pasta pai onde a pasta do projeto será criada. |
| `-h` | Ajuda do comando | Use `atk |
Sub-habilidades
| Sub-habilidade | Quando Usar | Referência |
|---|---|---|
| **create-project** | Criar novo projeto a partir do modelo, escolher modelo, `atk new` | create-project/create-project.md |
| **test-playground** | Testar localmente com o Agents Playground, `agentsplayground`, teste rápido | test-playground/test-playground.md |
| **test-teams** | Executar no Teams, devtunnel, sideload, teste no Teams, testar no Copilot | test-teams/test-teams.md |
| **provision-deploy** | Provisionar recursos do Azure, implantar na nuvem, `atk provision`, `atk deploy` | provision-deploy/provision-deploy.md |
| **troubleshoot** | Corrigir erros, 401, conflitos de porta, erros de YAML, bots desatualizados | troubleshoot/troubleshoot.md |
| **slack-to-teams** | Migrar bot do Slack para o Teams, ponte entre plataformas, Block Kit para Adaptive Cards | slack-to-teams/SKILL.md |
OBRIGATÓRIO: Antes de executar qualquer fluxo de trabalho, leia o documento da sub-habilidade correspondente.
Referências Compartilhadas
- manifest-and-yaml.md — Arquivos do projeto, configuração YAML, variáveis de ambiente, fluxo .localConfigs
- commands.md — Comandos do CLI do ATK: package, validate, share, collaborate
- templates.md — Catálogo completo de modelos com suporte de idioma
- experts/ — Mais de 100 arquivos de microespecialistas: SDK do Teams, SDK do Slack, ponte entre plataformas, implantação, modelos de IA, segurança, conversão de idioma
- docs/ — Guias de comparação de plataformas: UI, mensagens, identidade, infraestrutura, lacunas de recursos
Cadeias de Fluxo de Trabalho
Corresponda a intenção do usuário ao fluxo de trabalho válido mais simples.
| Intenção do Usuário | Fluxo de Trabalho (ler em ordem) |
|---|---|
| Construir novo aplicativo do zero | create-project → test-playground |
| Testar projeto existente localmente | test-playground (recomendado) ou test-teams |
| Implantar no Azure | provision-deploy |
| Corrigir bot quebrado | troubleshoot → re-testar |
| Migrar bot do Slack para o Teams | slack-to-teams |
OBRIGATÓRIO: Antes de executar qualquer fluxo de trabalho slack-to-teams, leia slack-to-teams/SKILL.md primeiro. A sub-habilidade contém um sistema de especialistas roteados com mais de 100 arquivos de microespecialistas para desenvolvimento de bots entre plataformas.
Resolução de Contexto do Projeto ATK
Resolva os valores de configuração apenas quando ausentes. Se um valor já for conhecido na sessão, reutilize-o.
Etapa 1: Detectar Projeto ATK
Se m365agentstoolkit*.yml existir na pasta atual, trate-o como um projeto ATK e analise a configuração.
Etapa 2: Resolver Configuração Comum
Resolva as variáveis referenciadas em m365agentstoolkit*.yml. Variáveis comuns: AZURE_OPENAI_API_KEY AZURE_OPENAI_ENDPOINT AZURE_OPENAI_DEPLOYMENT_NAME
Etapa 3: Coletar Valores Ausentes
Se os valores obrigatórios estiverem ausentes, solicite ao usuário apenas os que faltam.
Consulte manifest-and-yaml.md para detalhes completos do arquivo de configuração.
---
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.
Todos os arquivos
147 arquivosInstalar teams-app-developer
Baixe e extraia os arquivos de habilidade para o diretório .claude/skills/.
Baixar ZIPClone o repositório e copie os arquivos da habilidade para o seu projeto.
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
Copiar
