Créateur de Compétence

Guide pour créer des compétences qui étendent les capacités des agents IA, en mettant l'accent sur les SDK Azure et Microsoft Foundry.

Contexte requis : Lors de la création de compétences SDK ou API, les utilisateurs DOIVENT fournir le nom du package SDK, l'URL de la documentation ou une référence de dépôt sur laquelle la compétence doit être basée.

À propos des Compétences

Les compétences sont des packages de connaissances modulaires qui transforment les agents polyvalents en experts spécialisés :

1. Connaissances procédurales — Flux de travail multi-étapes pour des domaines spécifiques
2. Expertise SDK — Modèles d'API, authentification, gestion des erreurs pour les services Azure
3. Contexte de domaine — Schémas, logique métier, modèles spécifiques à l'entreprise
4. Ressources groupées — Scripts, références, modèles pour les tâches complexes

Principes Fondamentaux

1. La Concision est Clé

La fenêtre de contexte est une ressource partagée. Remettez en question chaque élément : « Cela justifie-t-il son coût en tokens ? »

Hypothèse par défaut : Les agents sont déjà compétents. Ajoutez uniquement ce qu'ils ne savent pas déjà.

2. Documentation Actuelle en Premier

Les SDK Azure changent constamment. Les compétences doivent instruire les agents à vérifier la documentation :

## Avant l'implémentation

Recherchez les modèles d'API actuels dans MCP `microsoft-docs` :

- Requête : « [nom du SDK] [opération] python »
- Vérifiez : Les paramètres correspondent à votre version SDK installée

3. Degrés de Liberté

Alignez la spécificité à la fragilité de la tâche :

4. Divulgation Progressive

Les compétences se chargent en trois niveaux :

1. Métadonnées (~100 mots) — Toujours en contexte
2. Corps SKILL.md (<5k mots) — Quand la compétence est déclenchée
3. Références (illimité) — Selon les besoins

Maintenez SKILL.md sous 500 lignes. Divisez en fichiers de référence en approchant cette limite.

Structure de Compétence

skill-name/
├── SKILL.md (obligatoire)
│   ├── Frontmatter YAML (name, description)
│   └── Instructions Markdown
└── Ressources Groupées (optionnel)
    ├── scripts/      — Code exécutable
    ├── references/   — Documentation chargée selon les besoins
    └── assets/       — Ressources de sortie (modèles, images)

SKILL.md

• Frontmatter : name et description. La description est le mécanisme de déclenchement.
• Corps : Instructions chargées seulement après déclenchement.

Ressources Groupées

N'incluez pas : README.md, CHANGELOG.md, guides d'installation.

Créer des Compétences SDK Azure

Lors de la création de compétences pour les SDK Azure, suivez ces modèles de manière cohérente.

Ordre des Sections de Compétence

Suivez cette structure (basée sur les compétences SDK Azure existantes) :

1. Titre — # Nom du SDK
2. Installation — pip install, npm install, etc.
3. Variables d'environnement — Configuration requise, avec un commentaire en ligne expliquant quand elle est requise. Si vous utilisez DefaultAzureCredential en production, incluez AZURE_TOKEN_CREDENTIALS (défini sur prod ou <credential_spécifique>)
4. Authentification — Utilisez une credential Microsoft Entra spécifique comme ManagedIdentityCredential ou WorkloadIdentityCredential pour la production. DefaultAzureCredential est seulement recommandé pour le développement local. Pour utiliser DefaultAzureCredential en production, définissez la variable d'environnement AZURE_TOKEN_CREDENTIALS sur prod ou la credential cible spécifique.
5. Flux de travail principal — Exemple minimal viable
6. Tableaux de fonctionnalités — Clients, méthodes, outils
7. Bonnes pratiques — Liste numérotée
8. Liens de référence — Tableau reliant à /references/*.md

Modèle d'authentification (Tous les langages)

Pour le développement local, utilisez DefaultAzureCredential qui supporte plusieurs méthodes d'auth. Pour la production, utilisez un type de credential spécifique ou configurez DefaultAzureCredential avec la variable d'environnement AZURE_TOKEN_CREDENTIALS définie sur prod ou spécifiez la credential cible.

# Python
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
# Dev local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credential_spécifique>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utilisez directement une credential spécifique en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
client = ServiceClient(endpoint, credential)

// C#
var credential = new DefaultAzureCredential();
var client = new ServiceClient(new Uri(endpoint), credential);

// Java
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ServiceClient client = new ServiceClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

// TypeScript
import {
  DefaultAzureCredential,
  ManagedIdentityCredential,
} from "@azure/identity";
// Dev local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credential_spécifique>
const credential = new DefaultAzureCredential({
  requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"],
});
// Ou utilisez directement une credential spécifique en production :
// Voir https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();
const client = new ServiceClient(endpoint, credential);

Ne codez jamais les credentials en dur. Utilisez les variables d'environnement.

Modèles de Verbes Standard

Les SDK Azure utilisent des verbes cohérents dans tous les langages :

Modèles Spécifiques au Langage

Voir references/azure-sdk-patterns.md pour les modèles détaillés incluant :

• Python : ItemPaged, LROPoller, gestionnaires de contexte, docstrings Sphinx
• .NET : Response<T>, Pageable<T>, Operation<T>, support du mocking
• Java : Modèle Builder, PagedIterable/PagedFlux, types Reactor
• TypeScript : PagedAsyncIterableIterator, AbortSignal, considérations navigateur

Gestion des SDK Dépréciés ou Rebrandés

Lorsqu'un SDK Azure a été déprécié ou rebrandé, mettez à jour les compétences pour guider les utilisateurs vers le package actuel tout en maintenant la compatibilité rétroactive :

1. Ajoutez un avis de migration en haut de la compétence :

> **⚠️ AVIS DE MIGRATION** : Le [Ancien Nom du Service] a été rebrandé en **[Nouveau Nom du Service]**. Bien que le package `old-package-name` reste disponible pour la compatibilité, **les nouveaux projets doivent utiliser `new-package-name`** qui fournit les dernières fonctionnalités et mises à jour.
>
> **Pour les nouveaux projets** : Utilisez le package `new-package-name` à la place.
>
> **Cette compétence reste valide** pour les projets existants utilisant `old-package-name`, mais sachez que vous utilisez le nom de package hérité. Les modèles d'API présentés ici sont compatibles avec les deux packages.

2. Affichez les deux options d'installation :

## Installation

### Package hérité (Ancien nom)

\`\`\`xml
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-old-package</artifactId>
    <version>4.2.0</version>
</dependency>
\`\`\`

### Package recommandé (Nouveau nom)

**Pour les nouveaux projets, utilisez le package rebrandé :**

\`\`\`xml
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-new-package</artifactId>
    <version>1.0.0</version>
</dependency>
\`\`\`

> **Note** : Les modèles d'API dans cette compétence s'appliquent aux deux packages. Remplacez les noms de packages et les imports selon vos besoins lors de l'utilisation de `azure-new-package`.

3. Quand mettre à jour une compétence existante vs. en créer une nouvelle :

• Mettez à jour la compétence existante si l'API est largement compatible (mêmes noms de classe/méthode ou similaires)
• Créez une nouvelle compétence + guide de migration si l'API a changé significativement (utilisez references/migration.md)
• Toujours faire référence croisée entre les anciennes et nouvelles compétences

Exemples :

• azure-ai-formrecognizer-java → azure-ai-documentintelligence (service rebrandé)
• azure-communication-callingserver-java → azure-communication-callautomation (déprécié, avec guide de migration)

Exemple : Structure de Compétence SDK Azure

---
name: skill-creator
description: |
  SDK Azure AI Example pour Python. À utiliser pour [fonctionnalités spécifiques].
  Déclencheurs : « exemple de service », « créer exemple », « lister exemples ».
---

# SDK Azure AI Example

## Installation

\`\`\`bash
pip install azure-ai-example
\`\`\`

## Variables d'environnement

\`\`\`bash
AZURE_EXAMPLE_ENDPOINT=https://<resource>.example.azure.com
AZURE_TOKEN_CREDENTIALS=prod # Requis seulement si DefaultAzureCredential est utilisé en production
\`\`\`

## Authentification

\`\`\`python
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
from azure.ai.example import ExampleClient

# Dev local : DefaultAzureCredential. Production : définissez AZURE_TOKEN_CREDENTIALS=prod ou AZURE_TOKEN_CREDENTIALS=<credential_spécifique>
credential = DefaultAzureCredential(require_envvar=True)
# Ou utilisez directement une credential spécifique en production :
# Voir https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
client = ExampleClient(
endpoint=os.environ["AZURE_EXAMPLE_ENDPOINT"],
credential=credential
)
\`\`\`

## Flux de travail principal

\`\`\`python

# Créer

item = client.create_item(name="example", data={...})

# Lister (pagination gérée automatiquement)

for item in client.list_items():
print(item.name)

# Opération longue

poller = client.begin_process(item_id)
result = poller.result()

# Nettoyage

client.delete_item(item_id)
\`\`\`

## Fichiers de référence

| Fichier                                        | Contenu                  |
| ---------------------------------------------- | ------------------------ |
| [references/tools.md](references/tools.md)     | Intégrations d'outils     |
| [references/streaming.md](references/streaming.md) | Modèles de flux continu   |

Processus de Création de Compétence

1. Rassembler le Contexte SDK — L'utilisateur fournit la référence SDK/API (REQUIS)
2. Comprendre — Rechercher les modèles SDK dans la documentation officielle
3. Planifier — Identifier les ressources réutilisables et la catégorie de domaine produit
4. Créer — Écrire SKILL.md dans .github/skills/<skill-name>/
5. Catégoriser — Créer un lien symbolique dans skills/<language>/<category>/
6. Tester — Créer les critères d'acceptation et les scénarios de test
7. Documenter — Mettre à jour README.md catalogue de compétences
8. Itérer — Affiner en fonction de l'utilisation réelle

Étape 1 : Rassembler le Contexte SDK (REQUIS)

Avant de créer une compétence SDK, l'utilisateur DOIT fournir :

Demandez à l'utilisateur si non fourni :

Pour créer cette compétence, j'ai besoin de :
1. Le nom du package SDK (ex. azure-ai-projects)
2. L'URL de documentation Microsoft Learn ou le dépôt GitHub
3. Le langage cible (py/dotnet/ts/java)

Recherchez d'abord dans la documentation officielle :

# Utilisez MCP microsoft-docs pour obtenir les modèles d'API actuels
# Requête : « [nom du SDK] [opération] [langage] »
# Vérifiez : Les paramètres correspondent à la dernière version du SDK

Étape 2 : Comprendre la Compétence

Rassemblez des exemples concrets :

• « Quelles opérations SDK cette compétence doit-elle couvrir ? »
• « Quels déclencheurs doivent activer cette compétence ? »
• « Quelles erreurs les développeurs rencontrent-ils couramment ? »

Étape 3 : Planifier la Catégorie de Domaine Produit

Les compétences sont organisées par langage et domaine produit dans le répertoire skills/ via des liens symboliques.

Catégories de Domaine Produit :

Déterminez la catégorie en fonction de :

1. Famille de services Azure (Stockage → data, Event Hubs → messaging)
2. Cas d'usage primaire (Agents IA → foundry)
3. Compétences existantes dans la même zone de service

Étape 4 : Créer la Compétence

Localisation : .github/skills/<skill-name>/SKILL.md

Convention de nommage :

• azure-<service>-<sous-service>-<language>
• Exemples : azure-ai-agents-py, azure-cosmos-java, azure-storage-blob-ts

Pour les compétences SDK Azure :

1. Recherchez les modèles d'API actuels dans MCP microsoft-docs
2. Vérifiez par rapport à la version SDK installée
3. Suivez l'ordre des sections ci-dessus
4. Incluez le code de nettoyage dans les exemples
5. Ajoutez des tableaux de comparaison des fonctionnalités

Écrivez d'abord les ressources groupées, puis SKILL.md.

Frontmatter :

---
name: skill-name-py
description: |
  SDK Azure Service pour Python. À utiliser pour [fonctionnalités spécifiques].
  Déclencheurs : « nom du service », « créer ressource », « opération spécifique ».
---

Étape 5 : Catégoriser avec des Liens Symboliques

Après la création de la compétence dans .github/skills/, créez un lien symbolique dans la catégorie appropriée :

# Modèle : skills/<language>/<category>/<short-name> -> ../../../.github/skills/<full-skill-name>

# Exemple pour azure-ai-agents-py dans python/foundry :
cd skills/python/foundry
ln -s ../../../.github/skills/azure-ai-agents-py agents

# Exemple pour azure-cosmos-db-py dans python/data :
cd skills/python/data
ln -s ../../../.github/skills/azure-cosmos-db-py cosmos-db

Nommage du lien symbolique :

• Utilisez des noms courts et descriptifs (ex. agents, cosmos, blob)
• Supprimez le préfixe azure- et le suffixe de langage
• Correspondez aux modèles existants dans la catégorie

Vérifiez le lien symbolique :

ls -la skills/python/foundry/agents
# Devrait afficher : agents -> ../../../.github/skills/azure-ai-agents-py

Étape 6 : Créer les Tests

Chaque compétence DOIT avoir des critères d'acceptation et des scénarios de test.

6.1 Créer les Critères d'Acceptation

Localisation : tests/scenarios/<skill-name>/acceptance-criteria.md

Matériaux source (par ordre de priorité) :

1. Documentation officielle Microsoft Learn (via MCP microsoft-docs)
2. Code source SDK du dépôt
3. Fichiers de référence existants dans la compétence

Format :

# Critères d'acceptation : <skill-name>

**SDK** : `package-name`
**Dépôt** : https://github.com/Azure/azure-sdk-for-<language>
**Objectif** : Critères d'acceptation pour tester la compétence

---

## 1. Modèles d'importation corrects

### 1.1 Importations du client

#### ✅ CORRECT : Client principal

\`\`\`python
from azure.ai.mymodule import MyClient
from azure.identity import DefaultAzureCredential
\`\`\`

#### ❌ INCORRECT : Chemin de module incorrect

\`\`\`python
from azure.ai.mymodule.models import MyClient # Incorrect - Client n'est pas dans models
\`\`\`

## 2. Modèles d'authentification

#### ✅ CORRECT : DefaultAzureCredential

\`\`\`python
credential = DefaultAzureCredential()
client = MyClient(endpoint, credential)
\`\`\`

#### ❌ INCORRECT : Credentials codées en dur

\`\`\`python
client = MyClient(endpoint, api_key="hardcoded") # Risque de sécurité
\`\`\`

Modèles critiques à documenter :

• Chemins d'importation (varient considérablement entre les SDK Azure)
• Modèles d'authentification
• Initialisation du client
• Variantes async (modules .aio)
• Anti-modèles courants

6.2 Créer les Scénarios de Test

Localisation : tests/scenarios/<skill-name>/scenarios.yaml

config:
  model: gpt-4
  max_tokens: 2000
  temperature: 0.3

scenarios:
  - name: basic_client_creation
    prompt: |
      Créez un exemple de base en utilisant le SDK Azure.
      Incluez l'authentification appropriée et l'initialisation du client.
    expected_patterns:
      - "DefaultAzureCredential"
      - "MyClient"
    forbidden_patterns:
      - "api_key="
      - "hardcoded"
    tags:
      - basic
      - authentication
    mock_response: |
      import os
      from azure.identity import DefaultAzureCredential
      from azure.ai.mymodule import MyClient

      credential = DefaultAzureCredential()
      client = MyClient(
          endpoint=os.environ["AZURE_ENDPOINT"],
          credential=credential
      )
      # ... reste de l'exemple fonctionnant

Principes de conception des scénarios :

• Chaque scénario teste UN modèle ou fonctionnalité spécifique
• expected_patterns — modèles qui DOIVENT apparaître
• forbidden_patterns — erreurs courantes qui ne doivent PAS apparaître
• mock_response — code complet et fonctionnant qui passe tous les contrôles
• tags — pour filtrage (basic, async, streaming, tools)

6.3 Exécuter les Tests

cd tests
pnpm install

# Vérifiez que la compétence est découverte
pnpm harness --list

# Exécutez en mode mock (rapide, déterministe)
pnpm harness <skill-name> --mock --verbose

# Exécutez avec Ralph Loop (amélioration itérative)
pnpm harness <skill-name> --ralph --mock --max-iterations 5 --threshold 85

Critères de succès :

• Tous les scénarios passent (taux de réussite 100%)
• Pas de faux positifs (les réponses mock réussissent toujours)
• Les modèles détectent les vraies erreurs

Étape 7 : Mettre à Jour la Documentation

Après la création de la compétence :

1. Mettre à jour README.md — Ajouter la compétence à la section appropriée du langage dans le Catalogue des Compétences

   • Mettre à jour le nombre total de compétences (ligne ~73 : > N skills in...)
   • Mettre à jour le lien Skill Explorer (ligne ~15 : Browse all N skills)
   • Mettre à jour le tableau de comptage des langues (lignes ~77-83)
   • Mettre à jour le comptage des sections de langage (ex. > N skills • suffix: -py)
   • Mettre à jour le comptage des catégories (ex. <summary><strong>Foundry & AI</strong> (N skills)</summary>)
   • Ajouter la ligne de compétence en ordre alphabétique dans sa catégorie
   • Mettre à jour le résumé de couverture de test (ligne ~622 : **N skills with N test scenarios**)
   • Mettre à jour le tableau de couverture de test — mettez à jour le comptage des compétences, le comptage des scénarios et les principales compétences pour le langage

2. Régénérer les données des GitHub Pages — Exécutez le script d'extraction pour mettre à jour le site de documentation

   cd docs-site && npx tsx scripts/extract-skills.ts

   Cela met à jour docs-site/src/data/skills.json qui alimente le site de documentation basé sur Astro. Puis reconstruisez le site de documentation :

   cd docs-site && npm run build

   Cela met les données dans docs/ qui est servi par GitHub Pages.

3. Vérifier AGENTS.md — Assurez-vous que le comptage des compétences est exact

Modèles de Divulgation Progressive

Modèle 1 : Guide de Haut Niveau avec Références

# Nom du SDK

## Démarrage rapide

[Exemple minimal]

## Fonctionnalités avancées

- **Flux continu** : Voir [references/streaming.md](references/streaming.md)
- **Outils** : Voir [references/tools.md](references/tools.md)

Modèle 2 : Variantes de Langage

azure-service-skill/
├── SKILL.md (aperçu + sélection de langage)
└── references/
    ├── python.md
    ├── dotnet.md
    ├── java.md
    └── typescript.md

Modèle 3 : Organisation par Fonctionnalité

azure-ai-agents/
├── SKILL.md (flux de travail principal)
└── references/
    ├── tools.md
    ├── streaming.md
    ├── async-patterns.md
    └── error-handling.md

Références de Modèles de Conception

Anti-Modèles

Liste de vérification

Avant de finaliser une compétence :

Prérequis :

• [ ] L'utilisateur a fourni le nom du package SDK ou l'URL de documentation
• [ ] Les modèles SDK vérifiés via MCP microsoft-docs

Création de compétence :

• [ ] La description inclut quoi ET quand (déclencheurs)
• [ ] SKILL.md sous 500 lignes
• [ ] L'authentification utilise DefaultAzureCredential
• [ ] Inclut le nettoyage/suppression dans les exemples
• [ ] Les références organisées par fonctionnalité

Catégorisation :

• [ ] Compétence créée dans .github/skills/<skill-name>/
• [ ] Lien symbolique créé dans skills/<language>/<category>/<short-name>
• [ ] Le lien symbolique pointe vers ../../../.github/skills/<skill-name>

Test :

• [ ] tests/scenarios/<skill-name>/acceptance-criteria.md créé avec modèles corrects/incorre