develop-ai-functions-example

Visão geral da skill develop-ai-functions-example

Para que serve a skill develop-ai-functions-example

A skill develop-ai-functions-example é um guia focado de implementação para criar ou modificar exemplos executáveis em examples/ai-functions/src/ dentro do repositório vercel/ai. O objetivo dela não é prompting genérico. Ela ajuda você a produzir exemplos que sigam as convenções do repositório para demos de funções do AI SDK, validação de providers e fixtures com perfil de teste.

Quem deve usar esta skill

Use a skill develop-ai-functions-example se você estiver:

• adicionando um novo exemplo para uma função do AI SDK
• adaptando um exemplo para outro provider
• validando se um provider oferece suporte a um recurso
• criando um repro mínimo ou fixture dentro da árvore de exemplos existente
• tentando se manter alinhado à estrutura do repo em vez de inventar um padrão próprio

Se você só quer perguntar a um LLM como generateText() funciona em abstrato, esta skill provavelmente é mais específica do que você precisa.

O trabalho real que ela resolve

A maioria dos usuários não está procurando texto explicativo. Quer um exemplo funcionando, na pasta certa, com o formato certo, usando a função correta do SDK e com menos erros específicos do repositório. O melhor jeito de entender develop-ai-functions-example é como um assistente de implementação com conhecimento do repo para a área de exemplos de AI Functions.

O que diferencia esta skill de um prompt genérico de código

Um prompt genérico pode até gerar código de exemplo, mas normalmente erra a taxonomia local e a lógica de onde os arquivos devem ficar. Esta skill adiciona contexto prático, como:

• as categorias de exemplo que já existem em examples/ai-functions/src/
• o mapeamento esperado entre tipo de recurso e diretório de destino
• o propósito desses exemplos no repositório: validação, demonstração e fixtures
• uma preferência por exemplos mínimos e executáveis, em vez de tutoriais amplos

Escopo ideal de uso

O encaixe mais forte de develop-ai-functions-example for Skill Examples está em trabalhos destas categorias:

• generate-text/
• stream-text/
• generate-object/
• stream-object/
• agent/
• embed/
• embed-many/
• generate-image/
• generate-speech/
• transcribe/
• rerank/
• middleware/

Esse escopo importa. A skill foi otimizada para desenvolvimento de exemplos dentro deste layout de repo, não para desenhar um app, a superfície de API de um SDK ou uma arquitetura de produção.

Como usar a skill develop-ai-functions-example

Contexto de instalação e onde ela se aplica

Use a orientação de develop-ai-functions-example install no contexto do repositório vercel/ai ou quando você quiser espelhar a estrutura de exemplos dele. Uma configuração comum é:

npx skills add vercel/ai --skill develop-ai-functions-example

Depois, acione a skill quando sua tarefa for especificamente criar, editar ou validar arquivos de exemplo em examples/ai-functions/src/.

Comece escolhendo a categoria de exemplo correta

Antes de pedir código, identifique a família de função de destino. Essa é a decisão de maior impacto, porque define tanto a pasta quanto o formato do exemplo.

Exemplos:

• saída de texto simples, em uma única resposta → generate-text/
• streaming de tokens ou chunks → stream-text/
• saída estruturada com schema → generate-object/
• saída estruturada em streaming → stream-object/
• embeddings para uma única entrada → embed/
• embeddings em lote → embed-many/
• fluxo multi-etapas com uso de ferramentas → agent/

Se você pular essa etapa, o exemplo gerado pode acabar usando a API errada por completo.

Quais informações a skill precisa de você

A qualidade de uso de develop-ai-functions-example depende muito de quão específico é o seu pedido. Informe:

• a função de destino, como generateObject() ou streamText()
• o provider e o modelo, se souber
• se o exemplo é para validação, demonstração em estilo de documentação ou fixture de teste
• entradas e saídas esperadas
• se há necessidade de streaming, tools, validação por schema ou middleware
• quaisquer restrições sobre dependências, nome de arquivo ou variáveis de ambiente

Uma entrada fraca:

• “Make an AI example.”

Uma entrada melhor:

• “Create a minimal generateObject() example under examples/ai-functions/src/generate-object/ that tests structured extraction from product review text using a Zod schema and a provider supported in this repo.”

Transforme um objetivo genérico em um prompt adequado para a skill

Um bom prompt de develop-ai-functions-example guide deixa claro o resultado esperado, o diretório de destino, a função e a intenção de validação.

Padrão útil:

• o que você quer criar
• onde isso deve ficar
• qual função do AI SDK deve ser usada
• quais suposições sobre provider são permitidas
• quão mínimo ou próximo de produção o exemplo deve ser
• como definir sucesso

Exemplo de prompt:

“Use develop-ai-functions-example to create a minimal example in examples/ai-functions/src/stream-text/ showing streamText() with a provider already used in the repo. Keep it short, runnable, and clearly focused on streaming output rather than app integration. Include any required env vars and explain why this belongs in stream-text/ instead of generate-text/.”

Leia primeiro o SKILL.md e depois inspecione exemplos próximos

Esta skill tem apenas um arquivo de suporte visível: SKILL.md. Leia-o primeiro, porque ele registra o mapa de categorias e a intenção específica do repo. Depois disso, inspecione exemplos vizinhos no diretório de destino que você pretende modificar. Isso costuma revelar mais rápido o padrão local de nomenclatura e implementação do que ler a documentação ampla do repositório.

Ordem prática de leitura:

1. skills/develop-ai-functions-example/SKILL.md
2. pasta de destino dentro de examples/ai-functions/src/
3. um ou dois exemplos irmãos mais próximos do recurso que você quer implementar
4. quaisquer imports específicos de provider ou padrões de env usados nas proximidades

Faça o exemplo corresponder ao propósito dele

O repositório usa exemplos para mais do que documentação. Seu prompt deve dizer qual destes objetivos está sendo priorizado:

• validação de suporte do provider
• demonstração de recurso
• fixture reproduzível
• experimentação iterativa

Por que isso importa:

• exemplos de validação devem ser mínimos e explícitos
• exemplos de demonstração devem destacar o comportamento principal da API
• fixtures devem evitar variações desnecessárias
• experimentos podem ser mais soltos, mas ainda precisam ficar na pasta correta

Mantenha a saída mínima, mas executável

As melhores saídas da skill develop-ai-functions-example geralmente fazem menos, não mais. Peça:

• uma chamada de função clara
• somente os imports necessários
• entradas óbvias
• tratamento simples da saída
• variáveis de ambiente explicitadas
• nenhum scaffolding de framework, a menos que a pasta já espere isso

Isso reduz falsos positivos em que o modelo adiciona código de app que acaba escondendo o comportamento real do SDK que você queria demonstrar.

Caminhos do repositório que vale citar explicitamente

Mencione os paths diretamente no pedido quando quiser uma saída alinhada ao repo. Alguns paths úteis:

• examples/ai-functions/src/generate-text/
• examples/ai-functions/src/stream-text/
• examples/ai-functions/src/generate-object/
• examples/ai-functions/src/stream-object/
• examples/ai-functions/src/agent/
• examples/ai-functions/src/embed/
• examples/ai-functions/src/embed-many/

Referências diretas de path ajudam a skill a escolher o padrão certo em vez de inventar um exemplo neutro.

Fluxo prático para criar um novo exemplo

Um fluxo confiável é:

1. identificar a família de função de destino
2. inspecionar exemplos irmãos nessa pasta
3. solicitar à skill com pasta, função, provider e objetivo
4. gerar o exemplo inicial
5. remover tudo o que não for necessário para validação ou demonstração
6. executar contra o provider pretendido
7. ajustar nomenclatura, entradas e tratamento de env para combinar com os arquivos próximos

Isso costuma ser mais rápido do que pedir um exemplo completo no escuro e depois tentar adaptá-lo ao repositório.

Quando usar esta skill em vez de um prompt comum

Use develop-ai-functions-example usage quando o principal risco for desencontro com o repositório: pasta errada, função errada do AI SDK, nível de complexidade inadequado ou uma demo que não se encaixa na árvore de exemplos. Use um prompt comum quando você precisar de ajuda arquitetural mais ampla fora de examples/ai-functions/src/.

FAQ da skill develop-ai-functions-example

A develop-ai-functions-example serve só para o repo vercel/ai

Ela é mais útil ali porque está ancorada na taxonomia de exemplos em examples/ai-functions/src/. Você ainda pode usá-la como padrão para o seu próprio repositório de exemplos, mas o valor cai se você não se importa em seguir essa estrutura.

Esta skill é amigável para iniciantes

Sim, se você já souber qual recurso quer demonstrar. Ela reduz o espaço de decisão ao mapear seu objetivo para a categoria de exemplo correta. É menos amigável para iniciantes se você ainda estiver decidindo entre geração de texto, geração estruturada, embeddings, agents ou middleware.

O que ela faz melhor do que um pedido simples de código

A principal vantagem é o melhor encaixe no repo. develop-ai-functions-example ajuda a evitar erros como colocar um exemplo de saída estruturada em uma pasta de texto simples, usar uma API sem streaming para uma demo de streaming ou transformar um fixture em algo excessivamente complexo com código de app sem relação.

Quando eu não devo usar a develop-ai-functions-example

Não use quando você precisar de:

• arquitetura de app em produção
• orientação de integração com UI
• um tutorial genérico do AI SDK
• aconselhamento de refatoração entre múltiplos repositórios
• estratégia de avaliação ou benchmarking além da criação de exemplos

Ela é intencionalmente limitada em escopo.

Preciso saber o provider exato antes

Nem sempre, mas a qualidade da saída melhora se você especificar um. Se não souber, peça um provider já usado em exemplos próximos, para que o arquivo gerado seja mais fácil de validar contra os padrões existentes do repo.

Ela pode ajudar com exemplos existentes, e não só com novos

Sim. Ela é útil para modificar ou enxugar um exemplo existente, especialmente quando você quer trocar a função do SDK, substituir o provider, simplificar um repro ou alinhar um arquivo à categoria correta.

Como melhorar a skill develop-ai-functions-example

Dê à skill um alvo concreto no repositório

A melhoria mais eficaz é informar a pasta de destino exata e a função. Compare:

Fraco:

• “Add an example for object extraction.”

Forte:

• “Use develop-ai-functions-example to add a minimal generateObject() example under examples/ai-functions/src/generate-object/ that extracts invoice fields from plain text and prints validated JSON.”

A versão mais forte elimina a ambiguidade sobre escolha de API e localização do arquivo.

Deixe claro o propósito da saída logo de início

O que mais importa para os usuários é saber se o exemplo serve para comprovar suporte, ensinar uso ou funcionar como fixture. Coloque isso na primeira frase do prompt. O formato do código muitas vezes muda com base nessa decisão.

Evite overengineering já no primeiro rascunho

Um modo comum de falha é receber uma resposta com wrappers extras, scaffolding de app ou preocupações misturadas. Peça explicitamente:

• código mínimo
• uma única responsabilidade
• sem UI
• sem setup de framework
• apenas comentários essenciais

Isso mantém o exemplo alinhado à árvore de exemplos, em vez de transformá-lo em um miniapp.

Peça aderência ao padrão local

Para melhorar os resultados da skill develop-ai-functions-example, diga ao modelo para imitar os exemplos próximos em nomenclatura, imports e tratamento de env. Essa pequena instrução muitas vezes pesa mais do que pedir “best practices”.

Exemplo:

• “Match the style of sibling files in examples/ai-functions/src/stream-text/ and avoid introducing a new pattern unless required.”

Seja explícito sobre entradas e formato de saída esperado

Outro modo comum de falha é uma lógica de demo vaga. Quando você especifica entradas de exemplo e a forma esperada da saída, o exemplo fica mais fácil de validar.

Detalhes de prompt melhores:

• texto de entrada ou payload
• formato esperado da resposta
• se a saída deve ser transmitida por streaming, exibida em log ou validada por schema
• o que deve contar como sucesso

Itere restringindo, não ampliando

Depois do primeiro rascunho, melhore removendo ambiguidades:

• troque “some provider” por um provider concreto
• troque “an object” por um schema
• troque “example script” pelo diretório de destino
• troque “works” por uma expectativa de saída testável

O melhor caminho de iteração para develop-ai-functions-example normalmente é reduzir o escopo, não adicionar mais recursos.

Verifique o encaixe na categoria antes de aceitar a saída

Antes de ficar com o resultado, pergunte:

• Esta é a pasta certa para a função usada?
• O exemplo está mínimo o suficiente para validação?
• Ele demonstra um comportamento central com clareza?
• Uma pessoa mantenedora entenderia por que ele pertence aqui?

Se não, revise o prompt antes de revisar o código. Muitas vezes esse é o ajuste mais rápido.

Melhore os prompts com suposições de provider e ambiente

Se o exemplo depender de credenciais ou de comportamento específico do provider, diga isso diretamente. Caso contrário, o modelo pode gerar código tecnicamente plausível, mas difícil de executar dentro do repositório.

Adições úteis:

• nomes obrigatórios de variáveis de ambiente
• suposições sobre o SDK do provider
• nome do modelo, se estabilidade importar
• se fallbacks são aceitáveis

Use exemplos irmãos como critério de aceitação

Uma forma prática de melhorar a qualidade da saída é avaliar o arquivo gerado comparando-o com exemplos próximos, não com padrões genéricos de código. Se ele parecer visivelmente mais complexo, menos focado ou estruturalmente diferente dos arquivos irmãos, peça uma reescrita alinhada ao padrão local.