develop-ai-functions-example

Présentation de la skill develop-ai-functions-example

À quoi sert develop-ai-functions-example

La skill develop-ai-functions-example est un guide de développement ciblé pour créer ou modifier des exemples exécutables dans examples/ai-functions/src/ au sein du dépôt vercel/ai. Son rôle n’est pas de faire du prompting généraliste. Elle vous aide à produire des exemples conformes aux conventions du dépôt pour les démos de fonctions AI SDK, la validation des providers et les fixtures de type test.

Pour qui cette skill est-elle utile

Utilisez la skill develop-ai-functions-example si vous devez :

• ajouter un nouvel exemple pour une fonction de l’AI SDK
• adapter un exemple à un autre provider
• vérifier si un provider prend en charge une fonctionnalité
• créer un repro minimal ou une fixture dans l’arborescence d’exemples existante
• rester aligné sur la structure du dépôt au lieu d’inventer votre propre modèle

Si vous voulez simplement demander à un LLM comment generateText() fonctionne de manière abstraite, cette skill est sans doute plus spécialisée que nécessaire.

Le vrai besoin auquel elle répond

La plupart des utilisateurs ne cherchent pas du texte explicatif. Ils veulent un exemple fonctionnel, dans le bon dossier, avec la bonne structure, en utilisant la bonne fonction SDK, et avec moins d’erreurs liées aux spécificités du dépôt. Il faut voir develop-ai-functions-example comme un assistant d’implémentation sensible au dépôt pour la zone des exemples AI Functions.

Ce qui la distingue d’un prompt de code générique

Un prompt générique peut rédiger un exemple de code, mais il passe généralement à côté de la taxonomie locale et de la logique de placement des fichiers. Cette skill apporte un contexte concret, par exemple :

• les catégories d’exemples déjà présentes dans examples/ai-functions/src/
• la correspondance attendue entre le type de fonctionnalité et le dossier cible
• le rôle de ces exemples dans le dépôt : validation, démonstration et fixtures
• une préférence pour des exemples minimaux et exécutables plutôt que pour des tutoriels larges

Périmètre idéal

Le meilleur cas d’usage de develop-ai-functions-example for Skill Examples couvre les catégories suivantes :

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

Ce périmètre est important. La skill est optimisée pour développer des exemples dans cette structure de dépôt, pas pour concevoir une application, une surface d’API SDK ou une architecture de production.

Comment utiliser la skill develop-ai-functions-example

Contexte d’installation et cas d’application

Suivez les indications de develop-ai-functions-example install dans le contexte du dépôt vercel/ai, ou lorsque vous souhaitez reprendre sa structure d’exemples. Une configuration courante est :

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

Ensuite, invoquez la skill lorsque votre tâche porte précisément sur la création, l’édition ou la validation de fichiers d’exemple sous examples/ai-functions/src/.

Commencez par choisir la bonne catégorie d’exemple

Avant de demander du code, identifiez la famille de fonctions cible. C’est la décision qui a le plus d’impact, car elle détermine à la fois le dossier et la forme de l’exemple.

Exemples :

• sortie texte simple en un seul appel → generate-text/
• streaming de tokens ou de chunks → stream-text/
• sortie structurée contrainte par un schéma → generate-object/
• sortie structurée en streaming → stream-object/
• embeddings pour une seule entrée → embed/
• embeddings pour des lots → embed-many/
• workflow multi-étapes avec outils → agent/

Si vous sautez cette étape, l’exemple généré peut utiliser la mauvaise API tout court.

Quelles informations fournir à la skill

La qualité d’utilisation de develop-ai-functions-example usage dépend fortement de la précision de votre demande. Indiquez :

• la fonction cible, par exemple generateObject() ou streamText()
• le provider et le modèle, si vous les connaissez
• si l’exemple sert à la validation, à une démonstration de style documentation ou à une fixture de test
• les entrées et sorties attendues
• si le streaming, les tools, la validation de schéma ou le middleware sont requis
• toute contrainte sur les dépendances, le nommage des fichiers ou les variables d’environnement

Une demande faible :

• « Fais un exemple AI. »

Une demande plus solide :

• « Crée un exemple minimal de generateObject() dans examples/ai-functions/src/generate-object/ qui teste l’extraction structurée à partir d’un texte d’avis produit avec un schéma Zod et un provider pris en charge dans ce dépôt. »

Transformer un objectif flou en prompt exploitable par la skill

Un bon prompt de develop-ai-functions-example guide précise le résultat attendu, le dossier cible, la fonction et l’intention de validation.

Structure utile :

• ce que vous voulez créer
• où cela doit se trouver
• quelle fonction AI SDK doit être utilisée
• quelles hypothèses de provider sont acceptables
• à quel point l’exemple doit être minimal ou proche d’un usage de production
• ce qui définira la réussite

Exemple de prompt :

« Utilise develop-ai-functions-example pour créer un exemple minimal dans examples/ai-functions/src/stream-text/ montrant streamText() avec un provider déjà utilisé dans le dépôt. Fais-le court, exécutable et clairement centré sur la sortie en streaming plutôt que sur l’intégration applicative. Indique les variables d’environnement nécessaires et explique pourquoi cela relève de stream-text/ plutôt que de generate-text/. »

Lire d’abord SKILL.md, puis inspecter les exemples voisins

Cette skill n’a qu’un seul fichier de support visible : SKILL.md. Lisez-le d’abord, car il synthétise la carte des catégories et l’intention spécifique au dépôt. Ensuite, inspectez les exemples voisins dans le dossier de destination que vous prévoyez de modifier. Vous récupérerez plus vite les conventions locales de nommage et de code qu’en lisant une documentation générale du dépôt.

Ordre de lecture pratique :

1. skills/develop-ai-functions-example/SKILL.md
2. le dossier cible sous examples/ai-functions/src/
3. un ou deux exemples frères les plus proches de la fonctionnalité visée
4. les imports spécifiques au provider ou les conventions d’env utilisées à proximité

Faire correspondre l’exemple à son objectif

Le dépôt n’utilise pas les exemples uniquement comme documentation. Votre prompt doit préciser lequel de ces objectifs vous privilégiez :

• validation de prise en charge par un provider
• démonstration d’une fonctionnalité
• fixture reproductible
• expérimentation itérative

Pourquoi c’est important :

• les exemples de validation doivent être minimaux et explicites
• les exemples de démonstration doivent mettre en avant le comportement clé de l’API
• les fixtures doivent éviter les variations inutiles
• les expérimentations peuvent être plus brutes, mais doivent quand même être placées dans le bon dossier

Garder la sortie minimale mais exécutable

Les meilleurs résultats de la skill develop-ai-functions-example en font généralement moins, pas plus. Demandez :

• un seul appel de fonction clair
• uniquement les imports nécessaires
• des entrées évidentes
• un traitement de sortie réduit
• des variables d’environnement indiquées explicitement
• aucune surcouche de framework sauf si le dossier l’attend déjà

Cela réduit les faux positifs où le modèle ajoute du code d’application qui masque le véritable comportement SDK que vous vouliez démontrer.

Chemins du dépôt à mentionner explicitement

Mentionnez les chemins directement dans votre demande si vous voulez un résultat aligné sur le dépôt. Chemins utiles :

• 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/

Des références de chemin explicites aident la skill à choisir le bon modèle au lieu d’inventer un exemple neutre.

Workflow pratique pour créer un nouvel exemple

Un workflow fiable consiste à :

1. identifier la famille de fonctions cible
2. inspecter les exemples frères dans ce dossier
3. solliciter la skill avec le dossier, la fonction, le provider et l’objectif
4. générer l’exemple initial
5. retirer tout ce qui n’est pas nécessaire à la validation ou à la démonstration
6. l’exécuter avec le provider visé
7. ajuster le nommage, les entrées et la gestion des variables d’environnement pour coller aux fichiers voisins

C’est généralement plus rapide que de demander d’emblée un exemple complet puis de le rétroadapter au dépôt.

Quand utiliser cette skill plutôt qu’un prompt ordinaire

Utilisez develop-ai-functions-example usage lorsque le principal risque est le décalage avec le dépôt : mauvais dossier, mauvaise fonction AI SDK, niveau de complexité inadapté, ou démo qui ne correspond pas à l’arborescence d’exemples. Utilisez un prompt ordinaire lorsque vous avez besoin d’aide d’architecture plus large en dehors de examples/ai-functions/src/.

FAQ sur la skill develop-ai-functions-example

develop-ai-functions-example est-elle réservée au dépôt vercel/ai

Elle y est la plus utile, car la skill est ancrée dans la taxonomie d’exemples de examples/ai-functions/src/. Vous pouvez malgré tout vous en servir comme modèle pour votre propre dépôt d’exemples, mais son intérêt baisse si vous ne cherchez pas à respecter cette structure.

Cette skill est-elle adaptée aux débutants

Oui, si vous savez déjà quelle fonctionnalité vous voulez démontrer. Elle réduit l’espace de décision en reliant votre objectif à la bonne catégorie d’exemple. Elle est moins adaptée aux débutants si vous hésitez encore entre génération de texte, génération structurée, embeddings, agents ou middleware.

Qu’apporte-t-elle de plus qu’une simple demande de code

Son principal avantage est un meilleur alignement avec le dépôt. develop-ai-functions-example vous aide à éviter des erreurs comme placer un exemple de sortie structurée dans un dossier de texte simple, utiliser une API non streaming pour une démo de streaming, ou surcharger une fixture avec du code d’application sans rapport.

Quand ne pas utiliser develop-ai-functions-example

Ne l’utilisez pas si vous avez besoin de :

• architecture d’application de production
• conseils d’intégration UI
• tutoriel générique sur l’AI SDK
• recommandations de refactorisation entre plusieurs dépôts
• stratégie d’évaluation ou de benchmarking au-delà de la création d’exemples

Son périmètre est volontairement restreint.

Faut-il connaître le provider exact dès le départ

Pas forcément, mais le résultat sera meilleur si vous en indiquez un. Si vous ne savez pas lequel choisir, demandez un provider déjà utilisé dans les exemples voisins afin que le fichier généré soit plus facile à valider par rapport aux conventions existantes du dépôt.

Peut-elle aider sur des exemples existants, pas seulement sur de nouveaux

Oui. Elle est utile pour modifier ou resserrer un exemple existant, en particulier si vous voulez changer la fonction SDK, remplacer le provider, simplifier un repro ou réaligner un fichier sur la bonne catégorie.

Comment améliorer la skill develop-ai-functions-example

Donner à la skill une cible de dépôt concrète

L’amélioration la plus efficace consiste à nommer le dossier de destination exact et la fonction concernée. Comparez :

Faible :

• « Ajoute un exemple d’extraction d’objet. »

Solide :

• « Utilise develop-ai-functions-example pour ajouter un exemple minimal de generateObject() dans examples/ai-functions/src/generate-object/ qui extrait des champs de facture à partir de texte brut et affiche un JSON validé. »

La version la plus précise supprime toute ambiguïté sur le choix de l’API et l’emplacement du fichier.

Indiquer l’objectif de sortie dès le début

Ce qui compte le plus pour les utilisateurs, c’est de savoir si l’exemple doit prouver une prise en charge, illustrer un usage ou servir de fixture. Mettez-le dans la première phrase de votre prompt. La forme du code change souvent selon cette décision.

Éviter la sur-ingénierie dans le premier jet

Un mode d’échec fréquent consiste à obtenir une réponse avec des wrappers inutiles, du scaffolding applicatif ou des responsabilités mélangées. Demandez explicitement :

• du code minimal
• une seule responsabilité
• pas d’UI
• pas de setup de framework
• uniquement les commentaires essentiels

Ainsi, l’exemple reste aligné sur l’arborescence d’exemples au lieu de dériver vers une mini-app.

Demander un alignement sur les patterns locaux

Pour améliorer les résultats de la skill develop-ai-functions-example, dites au modèle d’imiter les exemples voisins pour le nommage, les imports et la gestion des variables d’environnement. Cette petite instruction compte souvent davantage que demander de simples « bonnes pratiques ».

Exemple :

• « Reprends le style des fichiers frères dans examples/ai-functions/src/stream-text/ et n’introduis pas de nouveau pattern sauf nécessité. »

Être explicite sur les entrées et la forme de sortie attendue

Un autre mode d’échec courant est une logique de démo trop vague. Si vous précisez des exemples d’entrée et la forme de sortie attendue, l’exemple devient plus facile à valider.

Détails de prompt plus utiles :

• texte d’entrée ou payload
• forme de réponse attendue
• si la sortie doit être streamée, loggée ou validée par schéma
• ce qui doit être considéré comme une réussite

Itérer en resserrant, pas en élargissant

Après le premier jet, améliorez en supprimant l’ambiguïté :

• remplacez « some provider » par un provider concret
• remplacez « an object » par un schéma
• remplacez « example script » par le dossier cible
• remplacez « works » par une attente de sortie testable

Le meilleur chemin d’itération pour develop-ai-functions-example consiste généralement à réduire le périmètre, pas à ajouter des fonctionnalités.

Vérifier l’adéquation de la catégorie avant d’accepter le résultat

Avant de conserver le résultat, posez-vous ces questions :

• Est-ce le bon dossier pour la fonction utilisée ?
• L’exemple est-il suffisamment minimal pour servir à la validation ?
• Démontre-t-il clairement un comportement central ?
• Un mainteneur comprendrait-il pourquoi il a sa place ici ?

Si ce n’est pas le cas, révisez le prompt avant de réviser le code. C’est souvent le correctif le plus rapide.

Améliorer les prompts avec les hypothèses de provider et d’environnement

Si l’exemple dépend d’identifiants ou d’un comportement spécifique à un provider, dites-le explicitement. Sinon, le modèle peut produire un code plausible en théorie, mais difficile à exécuter dans le dépôt.

Ajouts utiles :

• noms des variables d’environnement requises
• hypothèses sur le SDK du provider
• nom du modèle si la stabilité compte
• si des solutions de repli sont acceptables

Utiliser les exemples frères comme critères d’acceptation

Une manière concrète d’améliorer la qualité de sortie consiste à juger le fichier généré par rapport aux exemples voisins, et non selon des standards de code génériques. S’il paraît nettement plus complexe, moins ciblé ou structurellement différent des fichiers frères, demandez une réécriture alignée sur le pattern local.