Publier tes ressources IA

Ton équipe garde des skills, des agents, des règles et des runbooks dans un dépôt Git. Tu déclares les dossiers dans le catalog-info.yaml de ce dépôt, et Astrolabe liste chaque ressource sur la page Ressources IA et sur un onglet du dépôt.

Le plugin doit être allumé d'abord : voir Allumer les ressources IA.

📚 Les quatre sortes de ressource

Sorte	Ce que c'est	Annotation	Ce qu'Astrolabe reconnaît sous le chemin
Skill	Un dossier d'instructions qu'un outil IA charge quand il en a besoin	astrolabe.forgeit.tech/ai-skills-path	Chaque dossier qui contient un SKILL.md
Agent	Un sous-agent ou un persona	astrolabe.forgeit.tech/ai-agents-path	Chaque fichier *.md qui commence par un name et une description (en-tête), et chaque fichier *.agent.md
Règle	Les instructions données à chaque session	astrolabe.forgeit.tech/ai-rules-path	AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, *.mdc, *.instructions.md et les *.md de .claude/rules
Runbook	Une procédure à suivre, pour une personne ou un assistant	astrolabe.forgeit.tech/ai-runbooks-path	Chaque fichier *.md

🗂️ Où mettre les fichiers dans le dépôt

Une valeur est un chemin depuis la racine du dépôt : un dossier ou un fichier. Mets plusieurs chemins sur une même ligne, séparés par des virgules.

acme-ai-kit/
├── catalog-info.yaml
├── AGENTS.md
├── skills/
│   └── code-review/
│       └── SKILL.md
├── .claude/
│   └── agents/
│       └── test-writer.md
├── .cursor/
│   └── rules/
│       └── typescript.mdc
└── runbooks/
    └── rotate-a-token.md

🚀 Déclarer le dépôt

1. Ouvre le catalog-info.yaml à la racine du dépôt.

2. Ajoute les annotations des sortes que tu publies, sous metadata.annotations. Garde seulement les lignes dont tu te sers.

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: acme-ai-kit
     description: Skills, agents et règles partagés par l'équipe plateforme
     tags: [ai, platform]
     annotations:
       astrolabe.forgeit.tech/ai-skills-path: skills, .claude/skills
       astrolabe.forgeit.tech/ai-agents-path: .claude/agents
       astrolabe.forgeit.tech/ai-rules-path: AGENTS.md, .cursor/rules
       astrolabe.forgeit.tech/ai-runbooks-path: runbooks
   spec:
     type: library
     lifecycle: production
     owner: group:default/platform-team

   Champ	Ce qu'il faut saisir	Exemple
   metadata.name	Le nom du composant du dépôt	acme-ai-kit
   metadata.tags	Les mots que les gens cherchent. Chaque ressource les reçoit	[ai, platform]
   spec.owner	Le groupe propriétaire du dépôt. Chaque ressource reçoit ce propriétaire	group:default/platform-team
   spec.lifecycle	experimental, production ou deprecated. Chaque ressource le reçoit	production

3. Valide le fichier et pousse-le sur la branche par défaut.

4. Si le dépôt n'est pas encore dans le catalogue, enregistre-le : voir Enregistrer un composant.

astuce

Un composant sans aucune annotation astrolabe.forgeit.tech/ai-… n'est jamais lu.

✨ Partir du modèle

Le modèle crée un dépôt avec un exemple de chaque sorte et les annotations déjà écrites.

1. Dans la barre latérale, clique sur La Fabrique.

2. Sur la carte AI resources repository, clique sur Choisir.

3. À l'étape The repository, remplis :

   Champ	Quoi écrire	Exemple
   Name	Des lettres minuscules, des chiffres et des tirets. Il nomme le dépôt et le composant	acme-ai-kit
   Description	À quoi servent les ressources de ce dépôt	Skills et agents de l'équipe plateforme
   Owner	L'équipe qui répond de ces ressources. Clique sur le champ et choisis	platform-team
   Kinds of resources	Coche Skills, Agents, Rules (AGENTS.md), Runbooks : un dossier et un exemple pour chaque sorte cochée	les quatre

4. Clique sur Suivant.

5. À l'étape Where to create it, choisis l'Hôte, puis remplis Propriétaire (l'organisation ou l'utilisateur du nouveau dépôt) et Dépôt (son nom).

6. Clique sur Vérifier, contrôle tes réponses, puis clique sur Créer.

Non vérifié sur une instance : la création elle-même, qui demande un hôte GitHub où l'instance peut écrire.

✅ Vérifier que ça a marché

1. Dans la barre latérale, clique sur Catalogue, puis sur le composant du dépôt.

2. Clique sur l'onglet Ressources IA. Il montre l'état de la lecture (Lu), le commit et les ressources trouvées, par exemple 2 skills et 1 agent.

3. Clique sur Relire le dépôt. Le message Lecture du dépôt lancée. apparaît en bas de l'écran, puis Dépôt relu : 3 ressources.

4. Dans la barre latérale, clique sur Ressources IA : chaque ressource est une carte, avec le propriétaire du dépôt.

✅ C'est fait !

La suite : Trouver et installer une ressource IA.

❓ Questions fréquentes

Puis-je mettre plusieurs sortes dans le même dossier ? Chaque chemin appartient à une sorte. Un SKILL.md trouvé sous ai-rules-path n'est pas publié comme règle : Astrolabe te dit d'ajouter son dossier à ai-skills-path.

D'où viennent le propriétaire et le cycle de vie d'une ressource ? Du catalog-info.yaml du dépôt (spec.owner, spec.lifecycle), jamais du fichier de la ressource.

Astrolabe exécute-t-il mes scripts ? Non. Voir la FAQ.

Comment retirer une ressource ? Supprime-la du dépôt, ou retire l'annotation. Elle disparaît à la prochaine lecture.

Où vois-je ce qui ne va pas dans mon dépôt ? Sur l'onglet Ressources IA du composant, sous Problèmes : voir Dépannage.