Noções Básicas de Habilidades de Agente

Q: Com que frequência devemos atualizar as habilidades?

A cada atualização de SDK, a cada mudança na política de runtimeVersion, e após qualquer postmortem que revele uma salvaguarda perdida. Execute npx expo-doctor na seção de verificação da habilidade.

O que uma Habilidade de Agente de SME móvel contém e quando invocá-la - dez exemplos para equipes que usam assistentes de IA no Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. Estas páginas documentam habilidades, não código de aplicativo. Uma habilidade é um playbook SKILL.md que seu agente lê antes de agir.

Pré-requisitos

As habilidades residem em seu repositório (ou registro de habilidades da equipe) ao lado do aplicativo que elas governam:

.cursor/skills/
├── eas-release/
│   └── SKILL.md
├── expo-router/
│   └── SKILL.md
├── mobile-testing/
│   └── SKILL.md
└── sdk-upgrade/
    └── SKILL.md

Fixe a pilha em cada cabeçalho de habilidade para que os agentes nunca se desviem para APIs desatualizadas:

## Pilha fixada
- React 19.2.3
- React Native 0.86.0
- Expo SDK 57 (`expo` ~57.0.4)

Escopo: As habilidades orquestram como um agente deve trabalhar. Manuais em linguagem humana em Noções Básicas de EAS Build, Noções Básicas de Expo Router e Noções Básicas de Testes Móveis permanecem a referência autoritativa.

Exemplos Básicos

1. O que é uma Habilidade de Agente

Uma Habilidade de Agente é um arquivo de instrução estruturado - tipicamente SKILL.md - que diz a um assistente de IA o que fazer, o que pedir e o que não fazer em uma tarefa móvel.

Artefato da habilidade	Propósito
`SKILL.md`	Frases de gatilho, entradas, saídas, salvaguardas
`references/`	Links profundos opcionais para ADRs internos ou runbooks
`examples/`	Prompts de invocação que passaram por revisão

Habilidades não são tutoriais de recursos - são contratos operacionais para desenvolvimento assistido
Habilidades devem ser fixadas por SDK - agentes alucinam APIs mais antigas do expo-router sem contexto de versão explícito
Uma habilidade = um domínio de decisão (lançamento, roteamento, revisão de módulo nativo, triagem de incidentes)

2. Estrutura Mínima de SKILL.md

Cada habilidade móvel deve começar com o mesmo esqueleto:

# Habilidade de Lançamento EAS
 
## O que esta habilidade faz
Guia build → submit → OTA com salvaguardas para SDK 57.
 
## Quando invocar
- Antes do primeiro `eas build` de produção
- Ao adicionar um novo perfil `eas.json`
- Ao planejar um hotfix apenas de JS vs binário da loja
 
## Entradas (obrigatórias)
- `eas.json`, `app.config.ts`, canal/branch de destino
- Último `updateId` conhecido como bom para contexto de rollback
 
## Saídas
- Lista de verificação de etapas com comandos
- Chamadas de risco (credenciais, runtimeVersion)
- Comandos de verificação (`eas channel:view`, `npx expo-doctor`)
 
## Salvaguardas
- Nunca OTA mudanças que afetam o nativo sem `eas build`
- Nunca envie para a trilha de produção sem um binário de QA interno
 
## Pilha fixada
React 19.2.3 · RN 0.86.0 · Expo SDK 57
 
## Prompts de exemplo
Veja §10 abaixo.

Entradas impedem que o agente adivinhe IDs de bundle ou perca runtimeVersion
Saídas devem ser verificáveis - comandos, não prosa
Salvaguardas são a seção de maior valor - agentes automatizam excessivamente ações da loja sem elas

3. Quando Invocar vs Quando Ler Documentos

Situação	Usar uma habilidade	Ler documentos humanos
"Estruturar `eas.json` para preview + produção"	Habilidade de Lançamento EAS	Perfis de Build e Flavors
"Adicionar rota tipada para `/orders/[id]`"	Habilidade Expo Router	Rotas Tipadas
"Escrever Maestro a partir dos critérios de aceitação"	Habilidade de Testes Móveis	Maestro E2E
"Atualizar 56 → 57"	Habilidade de Upgrade de SDK	Política de Upgrade de SDK
"Pico de crash após OTA"	Habilidade de Triagem de Incidentes	Runbook de Rollback

Invoque habilidades em pontos de decisão onde a automação incorreta é cara
Leia documentos ao aprender conceitos - habilidades assumem que você deseja um plano executável agora

4. Entradas que o Agente Deve Coletar

Antes de executar, uma habilidade bem escrita força o agente a coletar:

## Lista de verificação de entradas
- [ ] Versões do expo/react/react-native do `package.json`
- [ ] `app.config.ts` - esquema, bundleId, política de runtimeVersion
- [ ] Perfis `eas.json` em escopo
- [ ] Plataforma(s) de destino: ios | android | all
- [ ] Modo CNG: diretórios nativos gerados vs ios/android verificados no commit
- [ ] Contexto do incidente (se triagem): buildNumber, canal, delta de crash-free

Bundle ID / applicationId ausente quebra as habilidades Maestro e de envio
runtimeVersion ausente quebra as habilidades OTA - veja Política de Runtime Version
Agentes devem colar os valores coletados de volta para o humano para confirmação antes de comandos destrutivos

5. Saídas que Você Deve Esperar

Uma execução de habilidade deve terminar com entregas concretas:

Tipo de saída	Exemplo
Sequência de comandos	`eas build --profile production --platform all`
Diff de configuração	Snippet do perfil de envio do `eas.json`
Plano de teste	Casos Jest + esboço de `.maestro/checkout.yml`
Lista de verificação de revisão	Plugin de configuração de idempotência + portão `expo-doctor`
Árvore de decisão	Rollback OTA vs hotfix de loja com timestamps

Sem saída = habilidade falhou - rejeite respostas de agente que apenas resumem documentos
As saídas devem referenciar verificação - npx tsc --noEmit, npm test, eas channel:view
Para SDK 57, sempre inclua npx expo-doctor quando dependências ou plugins mudarem

6. Salvaguardas que Toda Habilidade Móvel Precisa

Copie estes padrões para cada SKILL.md:

## Salvaguardas (SDK 57)
1. Use `npx expo install` - nunca fixe manualmente versões de módulos Expo.
2. OTA (`eas update`) apenas quando `runtimeVersion` corresponder aos binários da loja ao vivo.
3. Mudanças de módulo nativo ou de permissão exigem `eas build`, não apenas OTA.
4. Nunca cometa segredos - apenas ambientes EAS e segredos de CI.
5. Execute `npx expo-doctor` antes de mesclar mudanças de dependência geradas pela habilidade.
6. Não edite `ios/` / `android/` gerados sob CNG - use plugins de configuração.
7. Pause o lançamento gradual/faseado da loja antes do binário de hotfix quando uma tempestade de crashes estiver ativa.

Salvaguardas convertem o entusiasmo do agente em disciplina de engenharia de lançamento
Emparelhe com Melhores Práticas de Habilidades de Agente para regras em toda a equipe

7. Fixação de SDK 57 em Habilidades

Agentes usam versões de dados de treinamento por padrão. Fixe explicitamente:

## Pilha fixada (obrigatório)
| Pacote | Versão |
| --- | --- |
| react | 19.2.3 |
| react-native | 0.86.0 |
| expo | ~57.0.4 |
 
## Específicos do SDK 57
- Nova Arquitetura padrão no RN 0.86 - verifique habilidades de TurboModule contra builds com NA ativado.
- `experiments.typedRoutes` gera `.expo/types/router.d.ts` - regen após mudanças em `app/`.
- Fluxos EAS suportam trabalhos `type: maestro` - prefira sobre scripts shell ad-hoc.

Re-fixe habilidades a cada atualização de SDK - habilidades desatualizadas são piores do que nenhuma habilidade
Verifique a saída do agente com npx expo-doctor e npx expo install --check

8. Composição de Habilidades (Não Duplique Documentos)

Habilidades delegam para documentos humanos; elas não os substituem:

## Referências (ler, não reescrever)
- Build: ../eas-build/eas-build-basics/eas-build-basics.md
- Envio: ../eas-build/eas-submit/eas-submit.md
- OTA: ../ota-updates/ota-updates-basics/ota-updates-basics.md
- Router: ../expo-router/typed-routes/typed-routes.md
- Testes: ../testing/jest-setup-for-expo/jest-setup-for-expo.md

Saída da habilidade = plano + comandos + portões
Saída do documento = conceitos + casos extremos + FAQs
Link em ambas as direções: habilidades apontam para documentos; documentos podem dizer "invocar habilidade X para configuração assistida"

9. Verificando a Saída da Habilidade

Após qualquer alteração assistida por habilidade:

# Alinhamento de dependência / nativo
npx expo-doctor
 
# Segurança de tipo (router, TS strict)
npx tsc --noEmit
 
# Portão de unidade/componente
npm run test:ci
 
# Opcional E2E smoke (Maestro)
maestro test .maestro/smoke.yml

Verificação	Detecta
`expo-doctor`	Descompasso de SDK, plugins mal configurados, configuração de app inválida
`tsc`	Rotas tipadas quebradas, `Href` inválido
Jest	Regressões na lógica de negócios que o agente refatorou
Maestro	Navegação e chrome nativo que o agente não mockou

Trate a saída da habilidade como um PR de engenheiro júnior - revise antes de mesclar
CI deve executar os mesmos portões - veja Portões de Qualidade de CI

10. Prompts de Exemplo de Invocação

Lançamento EAS:

Use a habilidade EAS Release. Pilha: Expo SDK 57, RN 0.86.
Entradas: eas.json anexado, canal de produção, último updateId bom abc123.
Objetivo: Hotfix JS para cópia de checkout - confirme se OTA é seguro, então forneça os comandos.
Salvaguardas: sem envio para a loja a menos que o doctor falhe em mudança nativa.

Expo Router:

Use a habilidade Expo Router. Adicione /settings/notifications com parâmetros tipados.
Habilite experiments.typedRoutes. Forneça construtor de href + esquema de link profundo myapp://.
Execute os passos de verificação do tsc.

Testes Móveis:

Use a habilidade Mobile Testing.
Critérios de aceitação:
- Convidado pode adicionar item ao carrinho
- Badge do carrinho mostra contagem
Entregue: 3 testes Jest + 1 fluxo Maestro. SDK 57, appId com.example.shop.

Upgrade de SDK:

Use a habilidade SDK Upgrade. Atualize expo 56 → 57.
Produza lista de verificação ordenada com portões expo-doctor e escaneamento de quebra de compatibilidade.
Não pule a regeneração do lockfile ou a recomendação de prebuild --clean.

Triagem de Incidentes:

Use a habilidade Incident Triage.
Crash-free caiu de 99,2% para 94% após OTA de produção 30 min atrás.
buildNumber 240012, iOS faseado em 50%. Árvore de decisão: rollback OTA vs pausa vs hotfix binário.

FAQs

As Habilidades de Agente são o mesmo que plugins de configuração do Expo?

Não. Plugins de configuração modificam projetos nativos no prebuild. Habilidades de Agente instruem assistentes de IA sobre como executar fluxos de trabalho da equipe com segurança. Você pode invocar a Habilidade de Módulo Nativo para revisar um plugin de configuração - camadas diferentes.

As habilidades devem residir no repositório do aplicativo ou em um registro central?

Repositório do aplicativo para convenções específicas do projeto eas.json e de roteamento. Registro central para playbooks de lançamento e incidentes em toda a organização. Sempre fixe a versão do SDK em ambos.

Uma SKILL.md pode cobrir toda a pilha móvel?

Evite isso. Divida por domínio de decisão para que as salvaguardas permaneçam afiadas. Uma habilidade monolítica dilui as fronteiras OTA vs nativas e produz automação insegura.

As habilidades substituem os runbooks de plantão?

Não. Habilidades aceleram a elaboração de listas de verificação e comandos. Habilidade de Triagem de Incidentes complementa - não substitui - Resposta a Incidentes da Loja.

Com que frequência devemos atualizar as habilidades?

A cada atualização de SDK, a cada mudança na política de runtimeVersion, e após qualquer postmortem que revele uma salvaguarda perdida. Execute npx expo-doctor na seção de verificação da habilidade.

Relacionados

Habilidade de Lançamento EAS - manual de build, submit, OTA
Habilidade Expo Router - rotas, parâmetros tipados, links profundos
Habilidade de Testes Móveis - Jest + Maestro a partir de AC
Habilidade de Upgrade de SDK - lista de verificação de upgrade do Expo 57
Habilidade de Triagem de Incidentes - clusters de crash e árvore de rollback
Melhores Práticas de Habilidades de Agente - resumo da equipe com 25 itens
Noções Básicas de EAS Build - referência humana para builds
Noções Básicas de Testes Móveis - pirâmide de testes

Versões da Pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Pré-requisitos

As habilidades residem em seu repositório (ou registro de habilidades da equipe) ao lado do aplicativo que elas governam:

.cursor/skills/
├── eas-release/
│   └── SKILL.md
├── expo-router/
│   └── SKILL.md
├── mobile-testing/
│   └── SKILL.md
└── sdk-upgrade/
    └── SKILL.md

Fixe a pilha em cada cabeçalho de habilidade para que os agentes nunca se desviem para APIs desatualizadas:

## Pilha fixada
- React 19.2.3
- React Native 0.86.0
- Expo SDK 57 (`expo` ~57.0.4)

Escopo: As habilidades orquestram como um agente deve trabalhar. Manuais em linguagem humana em Noções Básicas de EAS Build, Noções Básicas de Expo Router e Noções Básicas de Testes Móveis permanecem a referência autoritativa.

Exemplos Básicos

1. O que é uma Habilidade de Agente

Uma Habilidade de Agente é um arquivo de instrução estruturado - tipicamente SKILL.md - que diz a um assistente de IA o que fazer, o que pedir e o que não fazer em uma tarefa móvel.

Artefato da habilidade	Propósito
`SKILL.md`	Frases de gatilho, entradas, saídas, salvaguardas
`references/`	Links profundos opcionais para ADRs internos ou runbooks
`examples/`	Prompts de invocação que passaram por revisão

Habilidades não são tutoriais de recursos - são contratos operacionais para desenvolvimento assistido
Habilidades devem ser fixadas por SDK - agentes alucinam APIs mais antigas do expo-router sem contexto de versão explícito
Uma habilidade = um domínio de decisão (lançamento, roteamento, revisão de módulo nativo, triagem de incidentes)

2. Estrutura Mínima de SKILL.md

Cada habilidade móvel deve começar com o mesmo esqueleto:

# Habilidade de Lançamento EAS
 
## O que esta habilidade faz
Guia build → submit → OTA com salvaguardas para SDK 57.
 
## Quando invocar
- Antes do primeiro `eas build` de produção
- Ao adicionar um novo perfil `eas.json`
- Ao planejar um hotfix apenas de JS vs binário da loja
 
## Entradas (obrigatórias)
- `eas.json`, `app.config.ts`, canal/branch de destino
- Último `updateId` conhecido como bom para contexto de rollback
 
## Saídas
- Lista de verificação de etapas com comandos
- Chamadas de risco (credenciais, runtimeVersion)
- Comandos de verificação (`eas channel:view`, `npx expo-doctor`)
 
## Salvaguardas
- Nunca OTA mudanças que afetam o nativo sem `eas build`
- Nunca envie para a trilha de produção sem um binário de QA interno
 
## Pilha fixada
React 19.2.3 · RN 0.86.0 · Expo SDK 57
 
## Prompts de exemplo
Veja §10 abaixo.

Entradas impedem que o agente adivinhe IDs de bundle ou perca runtimeVersion
Saídas devem ser verificáveis - comandos, não prosa
Salvaguardas são a seção de maior valor - agentes automatizam excessivamente ações da loja sem elas

3. Quando Invocar vs Quando Ler Documentos

Situação	Usar uma habilidade	Ler documentos humanos
"Estruturar `eas.json` para preview + produção"	Habilidade de Lançamento EAS	Perfis de Build e Flavors
"Adicionar rota tipada para `/orders/[id]`"	Habilidade Expo Router	Rotas Tipadas
"Escrever Maestro a partir dos critérios de aceitação"	Habilidade de Testes Móveis	Maestro E2E
"Atualizar 56 → 57"	Habilidade de Upgrade de SDK	Política de Upgrade de SDK
"Pico de crash após OTA"	Habilidade de Triagem de Incidentes	Runbook de Rollback

Invoque habilidades em pontos de decisão onde a automação incorreta é cara
Leia documentos ao aprender conceitos - habilidades assumem que você deseja um plano executável agora

4. Entradas que o Agente Deve Coletar

Antes de executar, uma habilidade bem escrita força o agente a coletar:

## Lista de verificação de entradas
- [ ] Versões do expo/react/react-native do `package.json`
- [ ] `app.config.ts` - esquema, bundleId, política de runtimeVersion
- [ ] Perfis `eas.json` em escopo
- [ ] Plataforma(s) de destino: ios | android | all
- [ ] Modo CNG: diretórios nativos gerados vs ios/android verificados no commit
- [ ] Contexto do incidente (se triagem): buildNumber, canal, delta de crash-free

Bundle ID / applicationId ausente quebra as habilidades Maestro e de envio
runtimeVersion ausente quebra as habilidades OTA - veja Política de Runtime Version
Agentes devem colar os valores coletados de volta para o humano para confirmação antes de comandos destrutivos

5. Saídas que Você Deve Esperar

Uma execução de habilidade deve terminar com entregas concretas:

Tipo de saída	Exemplo
Sequência de comandos	`eas build --profile production --platform all`
Diff de configuração	Snippet do perfil de envio do `eas.json`
Plano de teste	Casos Jest + esboço de `.maestro/checkout.yml`
Lista de verificação de revisão	Plugin de configuração de idempotência + portão `expo-doctor`
Árvore de decisão	Rollback OTA vs hotfix de loja com timestamps

Sem saída = habilidade falhou - rejeite respostas de agente que apenas resumem documentos
As saídas devem referenciar verificação - npx tsc --noEmit, npm test, eas channel:view
Para SDK 57, sempre inclua npx expo-doctor quando dependências ou plugins mudarem

6. Salvaguardas que Toda Habilidade Móvel Precisa

Copie estes padrões para cada SKILL.md:

## Salvaguardas (SDK 57)
1. Use `npx expo install` - nunca fixe manualmente versões de módulos Expo.
2. OTA (`eas update`) apenas quando `runtimeVersion` corresponder aos binários da loja ao vivo.
3. Mudanças de módulo nativo ou de permissão exigem `eas build`, não apenas OTA.
4. Nunca cometa segredos - apenas ambientes EAS e segredos de CI.
5. Execute `npx expo-doctor` antes de mesclar mudanças de dependência geradas pela habilidade.
6. Não edite `ios/` / `android/` gerados sob CNG - use plugins de configuração.
7. Pause o lançamento gradual/faseado da loja antes do binário de hotfix quando uma tempestade de crashes estiver ativa.

Salvaguardas convertem o entusiasmo do agente em disciplina de engenharia de lançamento
Emparelhe com Melhores Práticas de Habilidades de Agente para regras em toda a equipe

7. Fixação de SDK 57 em Habilidades

Agentes usam versões de dados de treinamento por padrão. Fixe explicitamente:

## Pilha fixada (obrigatório)
| Pacote | Versão |
| --- | --- |
| react | 19.2.3 |
| react-native | 0.86.0 |
| expo | ~57.0.4 |
 
## Específicos do SDK 57
- Nova Arquitetura padrão no RN 0.86 - verifique habilidades de TurboModule contra builds com NA ativado.
- `experiments.typedRoutes` gera `.expo/types/router.d.ts` - regen após mudanças em `app/`.
- Fluxos EAS suportam trabalhos `type: maestro` - prefira sobre scripts shell ad-hoc.

Re-fixe habilidades a cada atualização de SDK - habilidades desatualizadas são piores do que nenhuma habilidade
Verifique a saída do agente com npx expo-doctor e npx expo install --check

8. Composição de Habilidades (Não Duplique Documentos)

Habilidades delegam para documentos humanos; elas não os substituem:

## Referências (ler, não reescrever)
- Build: ../eas-build/eas-build-basics/eas-build-basics.md
- Envio: ../eas-build/eas-submit/eas-submit.md
- OTA: ../ota-updates/ota-updates-basics/ota-updates-basics.md
- Router: ../expo-router/typed-routes/typed-routes.md
- Testes: ../testing/jest-setup-for-expo/jest-setup-for-expo.md

Saída da habilidade = plano + comandos + portões
Saída do documento = conceitos + casos extremos + FAQs
Link em ambas as direções: habilidades apontam para documentos; documentos podem dizer "invocar habilidade X para configuração assistida"

9. Verificando a Saída da Habilidade

Após qualquer alteração assistida por habilidade:

# Alinhamento de dependência / nativo
npx expo-doctor
 
# Segurança de tipo (router, TS strict)
npx tsc --noEmit
 
# Portão de unidade/componente
npm run test:ci
 
# Opcional E2E smoke (Maestro)
maestro test .maestro/smoke.yml

Verificação	Detecta
`expo-doctor`	Descompasso de SDK, plugins mal configurados, configuração de app inválida
`tsc`	Rotas tipadas quebradas, `Href` inválido
Jest	Regressões na lógica de negócios que o agente refatorou
Maestro	Navegação e chrome nativo que o agente não mockou

Trate a saída da habilidade como um PR de engenheiro júnior - revise antes de mesclar
CI deve executar os mesmos portões - veja Portões de Qualidade de CI

10. Prompts de Exemplo de Invocação

Lançamento EAS:

Use a habilidade EAS Release. Pilha: Expo SDK 57, RN 0.86.
Entradas: eas.json anexado, canal de produção, último updateId bom abc123.
Objetivo: Hotfix JS para cópia de checkout - confirme se OTA é seguro, então forneça os comandos.
Salvaguardas: sem envio para a loja a menos que o doctor falhe em mudança nativa.

Expo Router:

Use a habilidade Expo Router. Adicione /settings/notifications com parâmetros tipados.
Habilite experiments.typedRoutes. Forneça construtor de href + esquema de link profundo myapp://.
Execute os passos de verificação do tsc.

Testes Móveis:

Use a habilidade Mobile Testing.
Critérios de aceitação:
- Convidado pode adicionar item ao carrinho
- Badge do carrinho mostra contagem
Entregue: 3 testes Jest + 1 fluxo Maestro. SDK 57, appId com.example.shop.

Upgrade de SDK:

Use a habilidade SDK Upgrade. Atualize expo 56 → 57.
Produza lista de verificação ordenada com portões expo-doctor e escaneamento de quebra de compatibilidade.
Não pule a regeneração do lockfile ou a recomendação de prebuild --clean.

Triagem de Incidentes:

Use a habilidade Incident Triage.
Crash-free caiu de 99,2% para 94% após OTA de produção 30 min atrás.
buildNumber 240012, iOS faseado em 50%. Árvore de decisão: rollback OTA vs pausa vs hotfix binário.

FAQs

As Habilidades de Agente são o mesmo que plugins de configuração do Expo?

As habilidades devem residir no repositório do aplicativo ou em um registro central?

Uma SKILL.md pode cobrir toda a pilha móvel?

Evite isso. Divida por domínio de decisão para que as salvaguardas permaneçam afiadas. Uma habilidade monolítica dilui as fronteiras OTA vs nativas e produz automação insegura.

As habilidades substituem os runbooks de plantão?

Não. Habilidades aceleram a elaboração de listas de verificação e comandos. Habilidade de Triagem de Incidentes complementa - não substitui - Resposta a Incidentes da Loja.

Com que frequência devemos atualizar as habilidades?

Relacionados

Habilidade de Lançamento EAS - manual de build, submit, OTA
Habilidade Expo Router - rotas, parâmetros tipados, links profundos
Habilidade de Testes Móveis - Jest + Maestro a partir de AC
Habilidade de Upgrade de SDK - lista de verificação de upgrade do Expo 57
Habilidade de Triagem de Incidentes - clusters de crash e árvore de rollback
Melhores Práticas de Habilidades de Agente - resumo da equipe com 25 itens
Noções Básicas de EAS Build - referência humana para builds
Noções Básicas de Testes Móveis - pirâmide de testes

Versões da Pilha: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).

Noções Básicas de Habilidades de Agente

Buscar na documentação

Noções Básicas de Habilidades de Agente