Communitygithub.com

grusin-db/framework-skill-authoring

Méta-compétence qui transforme le code source de n'importe quel framework en une famille autonome de compétences pour agent, utilisable à partir du seul paquet installé (par exemple dans Databricks Genie Code ou tout agent de codage IA).

Qu'est-ce que framework-skill-authoring ?

Cette méta-compétence permet à un agent auteur disposant du code source d'un framework de produire une famille de compétences auto-suffisantes, conçues pour être utilisées par un agent consommateur qui n'a que le paquet installé (wheel, jar, etc.) — sans accès au dépôt, aux fichiers source ou à la documentation en ligne. Elle suit un modèle à deux agents : l'agent auteur analyse, cartographie, génère et valide les compétences pendant que le code source est disponible ; l'agent consommateur, exécuté dans un environnement sans source (bloc-notes de plateforme de données, IDE, ou agent CLI lisant le répertoire standard Agent Skills), utilise ces compétences pour piloter le framework via son API publique seulement. La sortie comprend un routeur d'entrée, des compétences de capacité par domaine fonctionnel, et un fichier d'instructions d'espace de travail. L'accent est mis sur l'auto-containment : tous les exemples de code sont complets et copiables, aucune référence aux chemins source n'est autorisée, et les compétences sœurs sont liées par leur nom. La validation inclut une simulation sans source pour chaque parcours utilisateur critique.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add grusin-db/framework-skill-authoring

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Création de compétences pour framework

Ceci est une méta-compétence : une compétence qui construit des compétences. Pointez-la vers n'importe quel framework ou bibliothèque dont vous avez le code source, et elle produit une famille de compétences pour agent autonome qu'un autre agent pourra utiliser plus tard avec uniquement le paquet installé (une wheel, un jar, ou équivalent) — sans source, sans dépôt, sans site de documentation.

Vous êtes l'agent auteur. Vous avez le code source. Votre travail consiste à capturer tout ce dont un agent consommateur futur aurait besoin, et à le cuire dans des compétences, car le consommateur ne pourra pas lire le code.

Quand utiliser cette compétence

  • « Crée des compétences pour agent pour <framework>. »
  • « Rends <library> utilisable par un assistant IA qui ne l'a que d'installée. »
  • « Rétro-ingénierie cette base de code en une famille de compétences. »
  • « Construis une compétence routeur d'entrée et des compétences de capacité pour notre framework. »
  • « Documente <framework> pour qu'un assistant dans un notebook / dans un IDE puisse le piloter. »

Si l'utilisateur ne veut qu'UNE seule compétence simple pour une tâche étroite, utilisez plutôt une approche de création de compétence simple — cette méta-compétence est destinée à produire une famille complète qui expose un framework.

Le modèle à deux agents (pourquoi l'auto-containment est primordial)

flowchart LR
  subgraph authorSide [Côté auteur : A LA source]
    src[Source du framework, tests, docs]
    author[Agent auteur + cette méta-compétence]
  end
  subgraph out [Artefact généré]
    fam[Famille de compétences :<br/>routeur d’entrée + compétences de capacité<br/>+ instructions d’espace de travail]
  end
  subgraph consumerSide [Côté exécution : PAS de source]
    consumer[Agent consommateur]
    pkg[Seulement le paquet installé]
  end
  src --> author
  author -->|analyse, cartographie, génère, valide| fam
  fam --> consumer
  pkg --> consumer

L'agent consommateur s'exécute généralement là où le paquet est installé mais pas le dépôt : un assistant de notebook sur une plateforme de données, un assistant IDE, ou un agent CLI qui lit les compétences depuis le répertoire standard Agent Skills. Il peut exécuter du code et appeler l'API publique du paquet, mais il ne peut pas ouvrir vos fichiers source.

Règle d'or : écrire pour le consommateur sans source

Tout ce dont le consommateur a besoin doit vivre à l'intérieur des compétences générées.

  • AUCUNE référence aux chemins des fichiers source (src/..., tests/..., fichiers de modules internes). Ils n'existent pas pour le consommateur.
  • TOUS les exemples de code sont complets et copiables, jamais « voir le fichier X ».
  • Référencez les compétences sœurs par nom de compétence, jamais par chemin de fichier.
  • Si le framework expose une API de documentation / découverte à l'exécution (une fonction qui renvoie la documentation des composants ou champs à l'exécution), intégrez-la dans les compétences comme échappatoire du consommateur pour les détails que vous n'avez pas intégrés en ligne.
  • Préférez les primitives publiques du framework plutôt que du code fait main ; les compétences existent pour que le consommateur utilise le framework au lieu de le contourner.

Règles complètes : authoring-rules.md.

AVANT DE COMMENCER

  1. Lisez ce fichier en entier. Il est court à dessein.
  2. Confirmez que vous avez bien la source du framework (dépôt, ou paquet décompressé avec du code lisible). Si vous n'avez que le paquet installé, vous êtes le consommateur, pas l'auteur — vous ne pouvez pas créer à partir d'une boîte noire.
  3. Copiez assets/templates/authoring-plan.md dans votre propre plan de travail et suivez-le. N'écrivez aucune compétence avant d'avoir rempli l'inventaire.
  4. Parcourez la bibliothèque de référence (tableau en bas) pour savoir quel guide répond à quelle question.

Le programme de l'agent auteur

Produisez d'abord ce plan (modèle : authoring-plan.md) et travaillez-le dans l'ordre :

  1. Inventoriez le framework — API publique, objet de configuration/paramètres, modèles de domaine, points d'entrée CLI, API de documentation à l'exécution, exemples/tests. Remplissez capability-inventory.md.
  2. Cartographiez l'inventaire vers la taxonomie de capacité et décidez quelles compétences émettre. Ignorez les domaines que le framework ne possède pas.
  3. Extrayez les vocabulaires conceptuels (couches, sémantiques de chargement, modes, sévérités, niveaux d'environnement, colonnes techniques, ...).
  4. Rédigez le(s) arbre(s) de décision du routeur d'entrée à partir des vrais points de décision du framework.
  5. Créez le fichier d'instructions d'espace de travail et le routeur d'entrée.
  6. Créez une compétence de capacité par domaine concerné.
  7. Passe en auto-containment — supprimez les chemins source, intégrez les exemples, branchez l'API de documentation à l'exécution, reliez les compétences sœurs par nom.
  8. Validez — lint structurel + simulation de consommateur sans source pour chaque parcours utilisateur critique (CUJ).
  9. Itérez sur les lacunes ; marquez les domaines réservés aux contributeurs comme hors de portée pour le consommateur.

Les quatre phases

Phase 1 — Analyser (vous avez la source)

Inventoriez ce que le framework peut faire et comment un utilisateur le pilote. Les signaux à lire et comment les lire se trouvent dans analyze-framework.md. Sortie : un capability-inventory.md rempli.

Phase 2 — Cartographier vers la taxonomie universelle

Pour chaque domaine de capacité, décidez : le framework l'a-t-il ? Si oui, émettez une compétence à partir du modèle de capacité ; si non, ignorez-le. La liste de contrôle des domaines sans marque et les règles de cartographie se trouvent dans universal-taxonomy.md. Pendant la cartographie, enregistrez également les vocabulaires conceptuels du framework en utilisant conceptual-taxonomies.md — ce sont les énumérations (types de chargement, modes, sévérités, ...) qu'un agent sans source ne devinera jamais.

Phase 3 — Générer la famille

Émettez, dans cet ordre, en utilisant les modèles et l'anatomie des compétences :

  1. Le fichier workspace-instructions (modèle).
  2. La compétence routeur d'entrée (modèle) — arbre de décision, modèle mental, références rapides, index des compétences, règles de configuration/chemins. Construisez ses arbres de décision à partir de decision-tree-patterns.md.
  3. Une compétence de capacité par domaine concerné (modèle).

Phase 4 — Valider

Lintez la structure, puis simulez un consommateur sans source effectuant chaque CUJ avec seulement les compétences + le paquet installé. Corrigez les lacunes et répétez. Procédure : validate-skills.md.

Ce que vous générez (structure de sortie)

Choisissez un préfixe de framework court en minuscules <fw> (par exemple le nom d'importation du paquet). Émettez :

<deploy-root>/
├── fichier d'instructions d'espace de travail  # toujours injecté : « lisez <fw> d'abord » + récupération
└── skills/
    ├── <fw>/                         # routeur d'entrée (arbre de décision + index)
    │   ├── SKILL.md
    │   ├── references/               # config/chemins, migration, références approfondies
    │   └── assets/templates/         # configurations de départ que le consommateur copie
    ├── <fw>-<capacité-a>/
    │   └── SKILL.md
    ├── <fw>-<capacité-b>/
    │   ├── SKILL.md
    │   └── <sous-guide>.md           # divulgation progressive quand c'est volumineux
    └── ...

La racine de déploiement exacte et le mécanisme des instructions d'espace de travail dépendent de la plateforme du consommateur — gardez les deux configurables, et ne codez jamais en dur un chemin spécifique à un fournisseur. Voir authoring-rules.md.

Conventions de nommage

  • Nom de la compétence routeur d'entrée = <fw> (le préfixe du framework seul).
  • Nom de la compétence de capacité = <fw>-<capacité>, minuscules + traits d'union, par exemple <fw>-onboarding, <fw>-qualité-des-données, <fw>-orchestration.
  • name: dans le frontmatter DOIT être égal au nom du répertoire de la compétence.
  • Gardez les noms descriptifs, jamais aide / utils / outils.

Bibliothèque de référence

GuideLisez-le quand
analyze-framework.mdPhase 1 : extraction des signaux de capacité depuis la source
universal-taxonomy.mdPhase 2 : quelles compétences de capacité émettre
conceptual-taxonomies.mdPhase 2 : les vocabulaires de domaine à capturer textuellement
decision-tree-patterns.mdPhase 3 : construction des arbres de décision pour le routeur + les compétences
skill-anatomy.mdPhase 3 : structure section par section de chaque SKILL.md
authoring-rules.mdTout au long : auto-containment + bonnes descriptions
validate-skills.mdPhase 4 : lint + simulation de consommateur sans source

Modèles

ModèleObjectif
authoring-plan.mdLe programme que vous copiez dans votre propre plan
capability-inventory.mdArtefact d'analyse de la phase 1 que vous remplissez
workspace-instructions.mdLe fichier d'instructions toujours injecté
entry-router.SKILL.mdLa compétence routeur de plus haut niveau du framework
capability.SKILL.mdUne compétence de capacité granulaire

Skills associés