Guide complet pour créer un SKILL dans Amazon Quick

Cet article s'appuie sur un cas réel — la genèse complète du SKILL « Audit SEO » — pour récapituler le travail nécessaire à la création d'un SKILL, les instructions utilisées et les pièges rencontrés. Il s'adresse à ceux qui veulent figer leurs workflows répétitifs en compétences réutilisables.

1. Qu'est-ce qu'un SKILL et pourquoi en créer un

Un SKILL est un pack de compétences réutilisable qui fige unworkflow multi-étapes. Une fois créé, une simple phrase déclenche tout le processus, sans avoir à tout réexpliquer à chaque fois.

Un SKILL est essentiellement un dossier :

skill-name/
├── SKILL.md          ← 核心：流程说明 + 触发词 + 输入 + 经验
├── scripts/          ← 可选：可复用的代码脚本
│   └── *.py
└── evals/            ← 可选：测试用例
    └── evals.json

Signaux indiquant qu'il faut en faire un SKILL: vous répétez cette tâche, elle comporte ≥2 étapes, elle produit un livrable clair et elle reste valable avec un autre objet (URL/client/projet).

2. Le processus global de création d'un SKILL (5 étapes)

La création d'une compétence est elle-même guidée par une « méta-compétence ». L'essentiel tient en 5 étapes :

III. Décomposition étape par étape : ce que fait concrètement chaque étape

Étape 1 : valider d'abord le workflow (le plus important)

Ne vous précipitez pas pour créer une compétence. Réalisez d'abord un besoin réel de bout en bout, par exemple : « aide-moi à vérifier le SEO de cette page web ». Pendant ce processus :

• Clarifierl'entréece qu'elle est (une URL ? un lot d'URL ?)
• Clarifierla sortiece qu'elle est (un rapport ? quel format ?)
• Noter les capacités utilisées à chaque étape (ouvrir une page web, exécuter du code, générer un Excel…)

Leçon pratique : notre compétence SEO a été extraite après avoir réellement audité plusieurs pages du site officiel d'une entreprise et ajusté à plusieurs reprises le format du rapport. En cours de route, l'utilisateur n'a cessé d'ajouter des exigences (ajouter les standards Bing, vérifier les sources officielles, transformer en matrice d'exécution, scinder en deux phases…), et tout cela est devenu la partie la plus précieuse de la compétence.

Étape 2 : confirmer le squelette de la compétence

Expliquez clairement à l'IA (ou laissez-la proposer) :

Étape 3 : extraire les données de session

Cette étape est réalisée automatiquement par l'outil : il scanne la session qui vient d'aboutir, extrait la liste des outils utilisés et génère un squelette SKILL.md avec un frontmatter YAML. Vous n'avez qu'à fournir ce qui a été défini à l'étape 2 : nom de la compétence, mots déclencheurs, champs de saisie, nom d'affichage, icône.

Instruction :extract_session_data

Étape 4 : rédiger SKILL.md (création centrale)

Sur la base du squelette, complétez les parties suivantes :

① frontmatter (en-tête du fichier)

---
name: seo-audit-skill
display_name: 「SEO 体检」
description: "一句话说清楚它做什么、什么时候该触发"
icon: "🔍"
trigger: SEO体检 audit 网站优化 网站SEO
inputs:
  - name: page_url
    description: "要体检的页面网址"
    required: true
scripts: [seo_audit.py, seo_matrix.py]
---

② Overview

2 à 3 phrases pour expliquer quoi faire et quand l'utiliser.

③ Workflow (étape par étape)

Pour chaque étape, indiquez le mode (deterministic action fixe / agentic nécessite un jugement), les entrées, les sorties, la méthode de vérification et que faire en cas d'échec.Privilégiez le « pourquoi », évitez les « il faut / interdit » rigides— l'IA qui exécute la compétence répond mieux au « raisonnement ».

④ Output

Définissez clairement le format du résultat final.

⑤ Lessons Learned (retours d'expérience)

C'est le point de bascule de la qualité d'une compétence, en quatre blocs :

• Do: quelles pratiques fonctionnent
• Don't: quels pièges éviter
• Common Failures: erreurs courantes + solutions
• When to Ask the User: quand s'arrêter et demander à un humain

Leçon du terrain : dans les Lessons de cette compétence, nous avons consigné tous les pièges réellement rencontrés — ne pas utiliser d'échappement \uXXXX en chinois, écrire les CSV avec utf-8-sig pour éviter les caractères illisibles dans Excel, un taux anormalement élevé d'alt d'image manquants est souvent un faux positif de lazy loading (à marquer « à vérifier » plutôt qu'à déclarer manquant), certains domaines bloquent le crawling en masse et nécessitent une vérification via navigateur… Ces « leçons douloureuses » rendent la compétence plus fiable à chaque exécution.

⑥ Scripts (facultatif mais fortement recommandé)

Si le workflow contient du code récurrent, extrayez-le dans un script placé dans scripts/，puis référencez-le dans SKILL.md. Nous avons transformé le « JS de collecte de signaux de page » et la « génération de matrice multi-pages » en deux scripts, garantissant un format de sortie identique à chaque fois.

Étape 5 : Enregistrer + tester

• Instruction d'enregistrement :save_skill(nom du SKILL + SKILL.md complet + scripts)
• Test de génération :generate_skill_evals(générer automatiquement quelques cas de test)
• Puisexécuter réellement une foispour vérifier — nous avons testé en conditions réelles avec deux scénarios, page unique et multi-pages, confirmant la détection de vrais problèmes (par exemple repérer plusieurs liens morts 404, détecter une incohérence entre le titre de partage social et le titre de la page).

IV. Comment itérer et distribuer après création

Itération et amélioration

Instruction :load_skill_for_improvement. Un SKILL ne se forme pas en une fois. Après quelques utilisations, améliorez selon les besoins :

• modifier le flux, ajouter des formats de sortie, ajuster les mots déclencheurs
• Lors de l'enregistrement,utilisez le même nom de SKILLpour écraser sur place (l'ancienne version est sauvegardée automatiquement)

Retour d'expérience : notre SKILL a été itéré de nombreuses fois — ajout du standard Bing, modification du format de matrice d'exécution, découpage en deux phases, ajout d'une double sortie Excel+Markdown, correction de l'alignement des noms de colonnes avec les exemples, et enfin changement de nom. Chaque cycle était : load_skill_for_improvement → modifier → save_skill écraser.

Renommer

modifiez le name et display_namedans le frontmatter, utilisez le nouveau nom save_skill, puis supprimez l'ancien dossier du SKILL.

Empaquetage et distribution

Compressez tout le dossier du SKILL en zip pour sauvegarder, migrer vers un autre ordinateur, ou partager avec des collègues (placez-le dans leur répertoire skills).

Portabilité entre outils

Pour l'utiliser dans d'autres outils IA (ChatGPT/Claude/Gemini), il faut « déplateformiser » : réécrire les noms d'outils propriétaires en descriptions de capacités génériques (« ouvrir une page web », « exécuter du code »), et intégrer les scripts en Markdown autonome, pour pouvoir coller l'ensemble comme prompt système / instruction personnalisée.

V. Aide-mémoire des instructions courantes

VI. Liste des pièges à éviter (tirés de vrais échecs)

1. Faire fonctionner d'abord, figer ensuite— n'écrivez pas de compétence à partir de rien.
2. Ne mettez en entrée que ce qui varie— les valeurs fixes se codent en dur dans le processus.
3. Lessons Learned doit consigner de vraies expériences— c'est la clé pour que la compétence « devienne de plus en plus stable à l'usage ».
4. Extraire le code répété dans des scripts— garantit un format de sortie cohérent et économise des tokens.
5. Tester obligatoirement après enregistrement— exécutez réellement une page unique + plusieurs pages pour vérifier qu'elle détecte de vrais problèmes.
6. Pièges d'encodage(si cela implique du chinois/génération de code) : pour écrire un fichier, utilisez encoding="utf-8", pour le CSV utilisez utf-8-sig, n'utilisez pas \uXXXX d'échappement ; pour le PDF en chinois, utilisez la police CID intégrée.
7. Pour l'itération, écrasez avec le même nom——name reste inchangé, l'ancienne version est sauvegardée automatiquement.

Conclusion

Créer une SKILL, c'est essentiellement :encapsuler un workflow réussi, avec ses jugements et ses leçons, en une capacité « rejouable en une phrase la prochaine fois ». Une bonne compétence ne se contente pas d'enregistrer les étapes : elle consigne aussi l'expérience de « comment bien faire les choses ».

Faites d'abord les choses proprement, puis rendez-les réutilisables — c'est tout l'esprit de la création d'une SKILL.