scaffold-exercises

Vue d’ensemble de la compétence scaffold-exercises

scaffold-exercises est une compétence orientée préparation qui sert à créer des répertoires d’exercices conformes aux conventions de nommage et de linting du dépôt. Elle est particulièrement utile lorsque vous devez ajouter une nouvelle section, créer des squelettes d’exercices ou standardiser des structures problem/solution/explainer sans avoir à deviner l’arborescence. L’objectif réel n’est pas seulement de « créer des dossiers », mais de produire un squelette d’exercice valide, prêt pour le contenu, la relecture et pnpm ai-hero-cli internal lint.

À quoi sert scaffold-exercises

Utilisez la compétence scaffold-exercises lorsque vous savez déjà quel contenu pédagogique vous voulez ajouter, mais que vous avez besoin d’un squelette de répertoire propre pour l’héberger. C’est un bon choix pour les auteurs de cours, les mainteneurs et les agents qui doivent créer des structures d’exercices reproductibles sur plusieurs sections.

Là où elle est la plus utile

La compétence est particulièrement efficace quand le dépôt impose des conventions strictes : sections numérotées, exercices numérotés et fichiers readme.md obligatoires dans chaque dossier de variante. L’installation de scaffold-exercises est surtout précieuse si votre workflow implique des squelettes fréquents, car elle réduit les erreurs de format avant même l’écriture du contenu.

Ce qu’elle attend de vous

Cette compétence suppose que vous pouvez fournir un numéro de section, un numéro d’exercice, un nom d’exercice et le type de variante visé. Si votre demande reste vague, le squelette peut quand même être créé, mais le résultat est meilleur lorsque l’entrée distingue clairement les cas d’usage problem, solution et explainer.

Comment utiliser la compétence scaffold-exercises

Installer scaffold-exercises

Installez la compétence scaffold-exercises avec :

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

C’est le chemin d’installation pratique de scaffold-exercises utilisé dans le dépôt. Une fois installée, servez-vous-en comme d’un workflow de création d’arborescence, pas comme d’une simple invite de rédaction générique.

Donner à la compétence un brief structuré

La meilleure utilisation de scaffold-exercises commence par un plan compact qui nomme la section cible, l’exercice et la variante souhaitée. Par exemple : « Create exercises/02-generation/02.01-rerank-basics/ with explainer/ and solution/ stubs; keep naming dash-case; ensure each readme has content. » C’est bien mieux que « scaffold a lesson », parce que cela indique à la compétence quels chemins créer et quels fichiers doivent exister.

Lire d’abord les bons fichiers

Commencez par SKILL.md, puis examinez les conventions d’exercices du dépôt concernant le nom des sections, les sous-dossiers obligatoires et le contenu des squelettes. Si le dépôt fournit des consignes adjacentes ailleurs, lisez ces fichiers avant de générer quoi que ce soit. Pour scaffold-exercises, les points de décision essentiels sont le format du répertoire, la variante par défaut et la nécessité éventuelle de fichiers de code, ou si un simple squelette avec readme.md suffit.

Respecter le modèle minimal valide du dépôt

Une bonne méthode pour scaffold-exercises consiste à créer d’abord les dossiers, puis à ajouter des fichiers readme.md non vides, et enfin à ajouter main.ts uniquement lorsque la variante contient réellement du code. Si vous créez un simple squelette, partir par défaut sur explainer/ est généralement plus propre que d’inventer des fichiers problem qui suggèrent un travail étudiant inachevé. Gardez des titres alignés avec le nom de l’exercice et évitez les liens cassés dans les premiers marqueurs provisoires.

FAQ sur la compétence scaffold-exercises

scaffold-exercises sert-il uniquement aux nouveaux exercices ?

Non. La compétence scaffold-exercises aide aussi lorsque vous ajoutez une nouvelle section ou que vous standardisez une série d’exercices existante. Elle est utile chaque fois que la structure d’exercices du dépôt doit être valide avant la rédaction du contenu approfondi.

Dois-je utiliser la compétence plutôt qu’une invite normale ?

Utilisez la compétence quand la structure compte davantage que la prose. Une invite normale peut décrire l’idée, mais scaffold-exercises est plus adaptée lorsque la sortie doit respecter des règles de nommage, des dossiers obligatoires et des squelettes compatibles avec le linting.

scaffold-exercises est-elle adaptée aux débutants ?

Oui, si vous pouvez identifier le nom de l’exercice et le dossier cible. L’erreur la plus fréquente chez les débutants est de sous-spécifier le type de variante ou d’ignorer le schéma de numérotation section/exercice, ce qui peut produire des chemins plausibles en apparence mais incompatibles avec le dépôt.

Quand ne faut-il pas utiliser scaffold-exercises ?

N’utilisez pas scaffold-exercises si vous avez seulement besoin du texte d’une leçon, d’un brainstorming ou d’un brouillon markdown ponctuel sans contrainte d’arborescence. C’est une compétence de structure de dépôt, pas un raccourci de génération de contenu.

Comment améliorer scaffold-exercises

Donner des chemins plus précis et clarifier l’intention des variantes

Le gain de qualité le plus important vient de la précision du répertoire exact et du rôle de chaque sous-dossier. Une demande solide indique ce qui doit exister, par exemple : « Create exercises/03-ranking/03.02-bm25-tuning/ with problem/, solution/, and explainer/ readmes; the problem/ folder should include TODOs, the solution/ folder should include the reference outline, and explainer/ should stay conceptual. » Cela aide la compétence scaffold-exercises à produire la bonne structure du premier coup.

Surveiller les modes d’échec courants

Les problèmes les plus fréquents sont une mauvaise numérotation, l’absence de readme.md, des espaces réservés vides et l’ajout de fichiers de code alors qu’un simple squelette suffirait. Une autre erreur courante consiste à mélanger dans le même chemin des noms de niveau section et de niveau exercice. Le guide scaffold-exercises fonctionne mieux quand vous séparez nettement les conventions de nommage et les attentes de contenu.

Itérer après le premier squelette

Après génération, vérifiez que chaque dossier contient les fichiers requis et que le texte de chaque readme correspond bien au type réel d’exercice. Si vous décidez ensuite que l’exercice doit contenir du code, ajoutez main.ts uniquement là où cela change réellement l’expérience d’apprentissage. Pour scaffold-exercises, la boucle d’amélioration la plus rapide est la suivante : générer, lancer le lint, ajuster les noms, puis enrichir le contenu.