scaffold-exercises

Vue d’ensemble de la skill scaffold-exercises

La skill scaffold-exercises aide un agent à créer des arborescences d’exercices conformes à une convention de contenu pédagogique stricte : sections numérotées, exercices numérotés, sous-dossiers de variantes comme problem/, solution/ et explainer/, ainsi qu’un minimum de fichiers suffisamment valides pour passer des contrôles orientés lint. Si vous créez du contenu de formation, des exercices d’atelier ou un repo d’apprentissage structuré, c’est précisément le problème que cette skill résout.

Dans quels cas scaffold-exercises est le plus utile

Utilisez scaffold-exercises lorsque vous connaissez déjà le plan pédagogique et que vous devez générer la structure de fichiers correctement, rapidement et de façon cohérente. C’est particulièrement adapté pour :

• mettre en place une nouvelle section de cours sous exercises/
• créer plusieurs squelettes d’exercices à partir d’un plan de programme
• ajouter des variantes problem, solution ou explainer sans avoir à deviner les règles de nommage
• éviter des dossiers de départ cassés qui échoueront plus tard aux vérifications du repo

Qui devrait installer scaffold-exercises

Le profil le plus adapté est quelqu’un qui travaille dans un repo déjà organisé autour d’exercices pédagogiques. La scaffold-exercises skill est particulièrement utile pour les maintainers, les auteurs de curriculum et les éditeurs de repo assistés par IA qui ont surtout besoin de chemins corrects et de fichiers placeholders fiables, plus que de génération de prose.

Ce qui distingue scaffold-exercises d’un prompt générique

Un prompt classique peut demander à une IA de « créer quelques dossiers d’exercices », mais scaffold-exercises ajoute une vraie discipline spécifique au repo :

• les dossiers de section suivent le format XX-section-name
• les dossiers d’exercice suivent le format XX.YY-exercise-name
• les noms sont en dash-case
• chaque exercice doit contenir au moins un dossier de variante
• chaque variante doit avoir un readme.md non vide
• des fichiers de code comme main.ts ne sont nécessaires que s’il y a réellement du code

Résultat : moins de chemins mal formés, moins de placeholders vides et moins de nettoyage après génération.

La question d’adoption à trancher en premier

Installez scaffold-exercises si votre principal risque est la dérive de structure, et non le manque d’originalité du contenu. Cette skill sert à produire un scaffold conforme à des conventions. Ce n’est pas, à elle seule, un planificateur de cursus complet, un rédacteur de leçons ou un générateur de code.

Comment utiliser la skill scaffold-exercises

Comment se passe généralement l’installation de scaffold-exercises

L’extrait du repo ne publie pas son propre installateur personnalisé dans SKILL.md, donc l’usage dépend de votre runtime de skills. Dans les environnements basés sur Skills, les équipes ajoutent souvent le repo source puis invoquent la skill scaffold-exercises par son nom. Si votre environnement le prend en charge, un schéma courant est :

npx skills add mattpocock/skills --skill scaffold-exercises

Si votre plateforme d’agent charge les skills autrement, pointez-la vers le dépôt mattpocock/skills puis sélectionnez scaffold-exercises.

Le premier fichier à lire avant d’utiliser scaffold-exercises

Commencez par :

• scaffold-exercises/SKILL.md

Cette skill est simple et autonome. L’aperçu du dépôt ne fait apparaître ni rules/, ni resources/, ni scripts auxiliaires ; l’essentiel du comportement utile est donc encodé directement dans ce seul fichier.

Les informations que scaffold-exercises attend de votre part

La skill fonctionne le mieux lorsque vous fournissez un plan avec quatre éléments :

1. le numéro et le titre de la section
2. les numéros et les titres des exercices
3. les variantes à inclure pour chaque exercice
4. si vous voulez uniquement des stubs ou un vrai code de départ

Sans cela, l’agent peut tout de même générer la structure, mais il devra appliquer des valeurs par défaut qui ne vous conviendront peut-être pas, en particulier sur le choix entre explainer/ et problem/.

Le prompt minimal qui fonctionne avec scaffold-exercises

Un prompt scaffold-exercises usage sommaire mais exploitable ressemble à ceci :

Use scaffold-exercises to create section 03-search-fundamentals under exercises/. Add exercises 03.01-tokenization-basics and 03.02-bm25-ranking. Each should have problem/ and solution/ folders with non-empty readme.md files. Stub only, no code yet.

Cela suffit car le prompt fournit la numérotation, les noms, l’emplacement et les types de variantes.

Un prompt plus solide qui améliore la qualité des résultats de scaffold-exercises

Un meilleur prompt explicite les choix par défaut :

Use scaffold-exercises for Skill Scaffolding in this repo. Create exercises/03-search-fundamentals/. Add:

• 03.01-tokenization-basics with explainer/
• 03.02-bm25-ranking with problem/ and solution/
• 03.03-query-expansion with problem/

For each variant, create a non-empty readme.md with the final exercise title and a one-sentence description. Do not add main.ts unless the variant includes code. Keep all names dash-case.

Pourquoi cela fonctionne mieux :

• cela supprime les ambiguïtés sur les variantes de dossiers
• cela évite la création inutile de fichiers de code
• cela préserve les conventions de nommage dès le départ
• cela indique concrètement à l’agent ce que signifie « non vide »

Le comportement par défaut à prévoir si le plan est incomplet

L’un des points les plus importants de la skill source : lors d’un simple stub, la valeur par défaut est explainer/ sauf indication contraire dans le plan. C’est utile pour des exercices conceptuels, mais cela peut être inadapté si vous avez en réalité besoin d’espaces de travail pour les apprenants. Si vous voulez des tâches pratiques, indiquez explicitement problem/.

Ce que scaffold-exercises va créer

La skill s’appuie sur un motif de répertoires répétable du type :

• exercises/01-section-name/
• exercises/01-section-name/01.01-exercise-name/problem/readme.md
• exercises/01-section-name/01.01-exercise-name/solution/readme.md

Pour des scaffolds de type stub, des dossiers contenant seulement un readme sont acceptables. Si vous ajoutez ensuite du code, alors main.ts doit être présent et contenir plus qu’un simple placeholder d’une ligne.

Workflow concret pour utiliser scaffold-exercises dans un vrai repo

Un bon workflow consiste à :

1. rédiger le plan de cursus en langage naturel
2. le convertir en noms de sections et d’exercices numérotés
3. préciser les variantes pour chaque exercice
4. demander à l’agent d’exécuter scaffold-exercises
5. relire les noms de chemins avant d’ajouter le contenu
6. lancer l’étape de lint ou de validation du repo
7. remplir ensuite seulement le code et la documentation plus complète

Cet ordre compte, car la skill est surtout efficace sur la structure en premier.

Les erreurs de nommage qui entraînent le plus de retouches

Les mauvaises entrées les plus fréquentes sont :

• l’absence de préfixes numériques
• l’utilisation d’espaces au lieu du dash-case
• la confusion entre la numérotation des sections et celle des exercices
• l’absence d’indication sur des dossiers problem, solution ou explainer

Si votre plan dit « Create an exercise on BM25 », l’agent doit encore trop inventer. S’il dit « Create 01.03-retrieval-with-bm25 inside 01-retrieval-skill-building with problem/ and solution/ », le résultat est généralement fiable.

Quand scaffold-exercises for Skill Scaffolding est un bon choix

scaffold-exercises for Skill Scaffolding convient bien lorsque votre principal goulot d’étranglement est la forme du repo et la cohérence. C’est un mauvais choix si vous avez besoin que l’outil génère automatiquement une pédagogie riche, des évaluations ou des explications soignées. Considérez-le comme un garant de structure, pas comme un substitut au travail de conception pédagogique.

FAQ sur la skill scaffold-exercises

scaffold-exercises est-il accessible aux débutants ?

Oui, à condition de déjà comprendre la structure d’exercice que vous visez. La skill elle-même est simple : elle impose surtout les conventions de nommage, la structure de dossiers et les fichiers minimaux requis. La partie la plus difficile consiste plutôt à décider à l’avance de votre curriculum et du choix des variantes.

Quand ne faut-il pas utiliser scaffold-exercises ?

Évitez scaffold-exercises si :

• votre repo n’utilise pas de dossiers de sections et d’exercices numérotés
• vous avez seulement besoin d’une leçon markdown unique, pas d’un arbre d’exercices
• vous voulez que l’IA invente toute l’architecture du cours à partir de zéro
• votre projet repose sur un contrat de fichiers différent de readme.md avec éventuellement main.ts

En quoi scaffold-exercises diffère-t-il d’une création manuelle des dossiers ?

Un scaffold manuel convient très bien pour un seul exercice. La valeur de scaffold-exercises usage apparaît quand vous créez de nombreux exercices et avez besoin d’une vraie cohérence. Il réduit le risque de noms invalides, de readmes vides et de conventions de dossiers mélangées qui cassent les vérifications en aval.

Est-ce que scaffold-exercises génère le contenu complet des exercices ?

Non. Sa valeur centrale est le scaffolding. Il peut créer des readmes minimaux et une structure placeholder, mais il ne faut pas le considérer comme un système complet de rédaction de leçons.

Faut-il avoir problem, solution et explainer à chaque fois ?

Non. Les règles source imposent seulement qu’au moins l’un d’eux soit présent. Pour les stubs, explainer/ est la valeur par défaut si rien d’autre n’est précisé. Choisissez les variantes selon l’objectif pédagogique de l’exercice, pas par automatisme.

scaffold-exercises est-il lié à une seule structure de repo ?

Oui, avec des choix assez marqués. La skill suppose une hiérarchie exercises/ et des conventions de numérotation précises. Si votre repo suit ce modèle, elle est utile. Sinon, vous passerez du temps à lutter contre ses hypothèses.

Comment améliorer l’usage de la skill scaffold-exercises

Donnez à scaffold-exercises un plan numéroté, pas une simple liste de thèmes

Le moyen le plus rapide d’obtenir de meilleurs résultats avec scaffold-exercises est d’arrêter de donner des thèmes vagues et de commencer à fournir des chemins cibles exacts. Comparez :

Faible :

• “Add some exercises about retrieval.”

Solide :

• “Create exercises/01-retrieval-skill-building/01.01-keyword-search, 01.02-bm25, and 01.03-hybrid-search.”

Le second prompt laisse à l’agent très peu de marge pour mal nommer les dossiers.

Précisez l’intention des variantes au lieu de laisser les valeurs par défaut décider

Si vous omettez les types de variantes, la skill peut choisir explainer/ pour les stubs. C’est efficace, mais cela peut ne pas correspondre à votre logique pédagogique. Indiquez clairement :

• utilisez problem/ pour les tâches destinées aux apprenants
• utilisez solution/ pour les corrigés ou références
• utilisez explainer/ pour du contenu purement conceptuel

Cette seule précision améliore nettement la qualité du scaffold.

Demandez des readmes minimaux mais valides

Un mode d’échec fréquent consiste à créer des placeholders techniquement présents mais peu utiles. Demandez à l’agent de mettre un titre et une description d’une phrase dans chaque readme.md. Les fichiers restent ainsi non vides et la rédaction ultérieure devient plus simple.

Évitez les fichiers de code inutiles

Une autre erreur fréquente consiste à générer main.ts partout. La skill source ne l’exige pas pour des stubs qui ne contiennent qu’un readme. Si vous voulez un scaffold léger, dites « readme-only unless code is explicitly needed ». Le premier passage restera ainsi plus propre.

Validez les noms avant de générer un grand nombre d’exercices

Pour des lots importants, demandez d’abord à l’agent de lister les chemins proposés, puis de les créer après validation. Cela permet de repérer les collisions de numérotation et les slugs maladroits avant d’avoir à renommer des dizaines de dossiers.

Itérez après le premier passage de scaffold-exercises

Après la première exécution, améliorez le résultat en vérifiant :

• la continuité de la numérotation
• la complétude des variantes
• l’utilité des readmes
• si chaque exercice appartient bien à la section choisie

Demandez ensuite à l’agent un second passage dédié uniquement aux corrections. La qualité d’un scaffold-exercises guide s’améliore nettement lorsque la génération et la relecture sont séparées.

Là où scaffold-exercises exige encore un jugement humain

La scaffold-exercises skill ne peut pas décider à votre place du bon enchaînement pédagogique, du niveau de difficulté des exercices ou de la couverture didactique pertinente. Les meilleurs résultats viennent d’un usage où la structure est automatisée par la skill, tandis que la logique de curriculum reste validée par un humain.