Création de Skills

Utilisé pour créer ou maintenir les skills propriétaires d'AgentDock. Le skill lui-même est un document descriptif lisible par le modèle ; les outils sont responsables de la vérification, de l'édition, de l'exécution des commandes, de l'empaquetage, de l'installation et de la validation.

Un skill cible doit être composé de deux parties :

Contrat de base portable
+
Instructions d'adaptation à l'hôte (optionnelles)

Après avoir supprimé les instructions d'adaptation spécifiques à AgentDock, le flux métier du skill, les références internes au package, le contrat des variables d'environnement et les scripts d'assistance doivent rester entièrement utilisables.

Quand utiliser

Utilisez ce skill pour traiter :

La création de nouveaux skills propriétaires ;
La modification, la refonte ou la mise à niveau de skills existants ;
L'ajustement des descriptions de déclenchement, du flux du corps du texte, des documents de référence ou des scripts d'assistance ;
L'ajout de tests, d'exemples, de contraintes de sécurité et de vérifications de portabilité ;
L'incrémentation de version et la validation du code source par rapport à la version actuellement activée.

N'utilisez pas ce skill pour la revue de sécurité formelle des skills tiers, la configuration de véritables informations d'identification ou le retour en arrière vers une version installée. Ces tâches relèvent de skill-installation.

Principes fondamentaux

Définissez d'abord quand le modèle doit sélectionner ce skill, puis rédigez le corps du texte.
Un skill décrit uniquement les méthodes, les limites et les choix d'outils ; il n'assume pas la responsabilité d'une exécution unifiée.
Le contrat de base d'un skill doit être indépendant de l'hôte ; les fichiers du package utilisent des chemins relatifs, l'environnement est injecté par l'hôte d'exécution.
Un skill simple doit de préférence avoir un seul fichier SKILL.md ; n'ajoutez des documents de référence, des scripts ou des tests que si nécessaire.
Toute modification du corps du texte, des documents de référence, des scripts ou du comportement doit être suivie d'une incrémentation de version sémantique.
Le contenu d'une même version et d'un même nom doit rester immuable.
Les valeurs d'environnement, l'état des appareils et les données d'exécution ne doivent pas être inclus dans le package du skill.
Toute validation doit porter sur la version actuellement installée et activée, et pas seulement sur le répertoire source.
Les skills propriétaires doivent passer la validation lint de ce skill, et pas seulement la validation d'installation du package.

Les spécifications complètes se trouvent dans le fichier references/skill-package-spec.md du package.

Procédure standard

1. Comprendre les besoins et les conditions de déclenchement

Déterminez d'abord :

Le vrai problème que l'utilisateur souhaite résoudre ;
Dans quelles conditions de requête le modèle doit sélectionner ce skill ;
Quelles tâches connexes n'appartiennent pas à ce skill ;
Quels outils réels doivent être appelés ;
Si des scripts d'assistance, des documents de référence ou des tests sont nécessaires ;
Si l'action implique du réseau, des écritures, des suppressions, des informations d'identification ou des opérations à haut risque.

N'utilisez pas de descriptions générales comme « gérer l'ensemble du cycle de vie d'une capacité ». La description doit permettre au modèle de décider de manière stable quand sélectionner ce skill.

2. Définir le périmètre des responsabilités

Le corps du texte doit au moins préciser :

Les cas d'utilisation et les cas hors périmètre ;
Les objets lus ou modifiés ;
Le comportement par défaut en lecture seule ;
Les règles de confirmation pour les opérations d'écriture et les opérations destructrices ;
Les preuves à fournir en cas d'échec.

Un skill doit être organisé autour d'un périmètre de compétence stable. Lorsque les besoins dépassent des responsabilités indépendantes, divisez-les en plusieurs skills.

3. Créer le répertoire source

Les skills propriétaires et communautaires normaux sont placés par défaut dans un dépôt agentdock-skills distinct :

skills/<nom-du-skill>/

Seuls les skills principaux, qui sont auto-amorcés avec le package d'installation d'AgentDock et fortement liés à la version du runtime, sont placés dans le dépôt principal d'AgentDock :

core-skills/<nom-du-skill>/

Choisissez la structure selon les besoins :

skills/<nom-du-skill>/
└── SKILL.md

skills/<nom-du-skill>/
├── SKILL.md
├── references/
├── scripts/
└── tests/

skills/<nom-du-skill>/
├── SKILL.md
├── run.py
└── tests/

Ne créez pas de répertoires vides pour la forme, et ne remettez pas les intégrations ordinaires dans le dépôt principal d'AgentDock.

4. Rédiger le Frontmatter

Analyse actuelle d'AgentDock :

---
name: exemple-skill
description: Explique clairement quand utiliser et quel problème résoudre
version: 1.0.0
---

Exigences :

name utilise un nom stable, court, en minuscules avec des traits d'union ;
description couvre à la fois les scénarios de déclenchement et le périmètre des compétences ;
version utilise le versionnage sémantique ;
Le Frontmatter doit être suivi d'un corps de texte Markdown non vide ;
N'ajoutez pas de champs de variables d'environnement ou d'exécution non supportés par l'analyseur actuel.

5. Rédiger le noyau portable

Par défaut, le corps du texte et les scripts du skill cible supposent uniquement :

Le répertoire de travail actuel est la racine du package du skill ;
Les ressources du package sont accessibles via des chemins relatifs ;
Les variables d'environnement proviennent de l'environnement du processus actuel ;
L'hôte d'exécution est responsable de la sélection des outils, du changement de répertoire et de l'injection de l'environnement ;
Ne dépend pas du répertoire d'installation, du répertoire d'état ou des variables spécifiques d'AgentDock.

Lorsqu'il y a un script racine, l'exemple d'exécution générale doit être rédigé comme suit :

printf '%s' '{"skill_action":"status"}' | python3 run.py

Les éléments suivants ne doivent pas être considérés comme des conditions préalables à l'exécution du noyau :

~/.agentdock/skill-store/installed/... ;
Un numéro de version d'installation fixe ;
AGENTDOCK_DIR, AGENTDOCK_HOME ou AGENTDOCK_SKILL_DIR pour localiser les scripts du package ou les données privées ;
skill_env, exec_command ou skill:// ;
Des chemins absolus utilisateur fixes ;
La lecture active ou le source des fichiers d'environnement privés d'AgentDock.

Les appels d'outils AgentDock peuvent apparaître dans une section séparée « Adaptation/Validation AgentDock », mais après avoir supprimé cette section, le skill doit toujours être utilisable.

6. Déclarer les variables d'environnement

Chaque skill cible nécessitant une configuration doit déclarer explicitement les variables dans le corps du texte :

## Variables d'environnement

| Variable | Type | Obligatoire | Description |
|---|---:|---|
| EXAMPLE_BASE_URL | config | Oui | Adresse du service |
| EXAMPLE_API_KEY | secret | Oui | Clé API |

Le type se distingue au moins entre config et secret, et précise quelles fonctionnalités sont indisponibles en cas d'absence de variable.

Le skill cible déclare uniquement le nom et l'utilisation des variables, pas les chemins de sauvegarde privés d'AgentDock. Les scripts d'assistance lisent les variables uniquement à partir de l'environnement du processus actuel.

Lors de la validation locale dans AgentDock, les valeurs d'environnement sont gérées par skill_package env_set/env_unset/env_list, et injectées dans le sous-processus via le contexte skill de exec_command. L'environnement n'est pas écrit dans le processus principal d'AgentDock ou dans l'environnement système.

7. Rédiger les documents de référence

Le contenu approprié pour references/ comprend :

Des descriptions de protocoles stables ;
Des listes de vérification longues ;
Des tableaux de champs API ou de codes d'erreur ;
Des documents de contexte qui ne nécessitent pas d'être chargés complètement à chaque fois.

Le SKILL.md cible utilise des chemins relatifs dans le package, par exemple :

references/api.md

N'utilisez pas skill://<nom>/... comme contrat de référence de base, et ne dépendez pas du répertoire d'installation d'un autre skill. Lors de la validation du package actuellement activé, AgentDock peut lire les ressources via read_file skill://<nom>/....

8. Rédiger les scripts d'assistance

Les scripts d'assistance sont des ressources optionnelles, pas le skill lui-même. Lorsqu'un script est nécessaire :

L'entrée est un objet JSON via stdin ;
Le champ d'action de haut niveau utilise systématiquement skill_action ;
Les secrets sont lus uniquement à partir de l'environnement du processus actuel ;
Les secrets ne sont pas passés en paramètres de ligne de commande ;
La sortie est un JSON structuré ;
En cas d'erreur, retourne un code stable et un message lisible ;
Les vérifications d'état sont prioritaires en lecture seule ;
Les opérations d'écriture respectent les règles de confirmation de l'utilisateur ;
Les journaux et les erreurs ne doivent pas divulguer de secrets ;
Les fichiers du package utilisent des chemins relatifs ou se basent sur le répertoire du script lui-même.

Entrée recommandée :

{
  "skill_action": "status"
}

Exécution générale dans le répertoire racine du package du skill :

python3 run.py

Lors de la validation dans AgentDock, utilisez exec_command avec skill: "<nom-du-skill>" pour lier le répertoire actuellement activé à un environnement indépendant, sans analyser manuellement le répertoire de version.

9. Exécuter la validation de portabilité (lint)

Le run.py de ce skill fournit :

status : rapporte la version de lint et le nombre de règles ;
lint : vérifie le noyau portable et les problèmes de liaison avec l'hôte du skill cible.

Exemple d'entrée :

{
  "skill_action": "lint",
  "source": "/chemin/vers/agentdock-skills/skills/example-skill"
}

Le résultat comprend :

portable ;
error_count ;
warning_count ;
Pour chaque problème : code, severity, fichier, numéro de ligne, description et suggestion de correction.

Les erreurs incluent : les chemins de répertoire de version installée en dur, la dépendance à des variables de répertoire spécifiques à AgentDock, la lecture active de fichiers d'environnement AgentDock et les chemins absolus utilisateur fixes. Les avertissements (warnings) incluent la présence d'outils ou d'URI spécifiques à AgentDock dans le SKILL.md cible, qui doivent être confirmés comme n'existant que dans les instructions d'adaptation optionnelles.

Lors de l'exécution de lint sur un répertoire installé, le fichier .agentdock-install.json généré par l'installateur AgentDock à la racine du package est ignoré. Ce fichier fait partie de l'accusé de réception de l'installation par l'hôte, pas du contenu du package du skill ; les fichiers du même nom apparaissant dans d'autres répertoires du package sont toujours scannés normalement.

Dans AgentDock, après avoir installé une nouvelle version de skill-authoring, exécutez :

exec_command
  skill: skill-authoring
  cmd: python3 run.py
  stdin: {"skill_action":"lint","source":"/chemin/vers/source"}

Lors de la création ou de la modification d'un skill propriétaire, portable doit être true ; les avertissements doivent être corrigés un par un, ou justifiés comme appartenant à une adaptation facultative à l'hôte.

10. Rédiger les tests

Les tests couvrent les risques réels, en tenant compte au moins de :

Le Frontmatter et le corps du texte sont analysables ;
Une entrée qui n'est pas un objet JSON échoue clairement ;
Un skill_action inconnu échoue clairement ;
En cas de variable d'environnement manquante, seul le nom de la variable est signalé, pas sa valeur ;
Les vérifications d'état en lecture seule ne produisent pas d'écriture ;
Une action destructive sans confirmation est refusée ;
Les journaux et les erreurs ne contiennent pas de secrets ;
En cas d'absence de plateforme ou de dépendance, un message de diagnostic est retourné ;
Le package est exécuté depuis sa racine avec une commande relative ;
Les scripts ne dépendent pas des répertoires privés d'AgentDock.

11. Vérifications de sécurité et de qualité

Avant la soumission, vérifiez :

Absence de mots de passe réels, jetons, cookies, caches d'authentification ou fichiers de session dans le package ;
Absence de .env, cache, base de données, captures d'écran, fichiers téléchargés ou résultats d'exécution ;
Absence de __pycache__, *.pyc, node_modules ou artefacts de compilation ;
Absence de chemins absolus utilisateur fixes, de liens symboliques ou d'échappements de chemin ;
Absence d'exemples d'anciens protocoles d'exécution unifiés, d'anciens outils d'environnement ou d'anciennes listes ;
Les cibles réseau, les écritures de fichiers, les suppressions, les téléchargements et les changements de permissions sont clairement décrits ;
Les installations de dépendances ne sont pas exécutées de manière cachée.

Génération ou restauration interdite :

agentdock.yaml ;
skill_run ;
skill_env_manage ;
AGENTDOCK_OPERATION ;
Ancien protocole PLUGIN_* ;
Ancienne liste operation ou entrypoint ;
Exécuteur unifié de skills ou ancien Skill Runtime.

L'état privé des appareils et les valeurs d'environnement d'AgentDock appartiennent uniquement à l'hôte et ne doivent pas entrer dans le package.

12. Incrémenter la version

Pour une simple correction de faute de frappe n'affectant pas le comportement, la version de correctif peut être incrémentée ;
Pour l'ajout d'une capacité compatible, d'une variable, d'une action ou d'une référence, la version mineure est incrémentée ;
Pour un changement de périmètre de responsabilité, la suppression d'une capacité existante ou l'introduction d'un flux incompatible, la version majeure est incrémentée.

Avant l'installation, comparez la version actuellement installée et la nouvelle source. Ne remplacez pas un contenu différent par la même version.

13. Validation et installation locale

Effectuez au moins :

Vérification du répertoire et du Frontmatter ;
Vérification que la version a été correctement incrémentée ;
Vérification des fichiers interdits, des liens symboliques et des secrets réels ;
Vérification syntaxique et tests intégrés des scripts d'assistance ;
Exécution de skill-authoring lint, confirmation de portable=true et examen des avertissements ;
Utilisation de skill_package validate pour valider la conformité au niveau du package ;
Utilisation de skill_package install pour installer et activer ;
Vérification via agentdock_context que le nom et la description sont dans l'index léger ;
Vérification du corps du texte actuellement activé via read_file skill://<nom>/SKILL.md ;
Lecture d'au moins un document de référence s'il y en a ;
S'il y a un script d'assistance, exécution d'un status en lecture seule sur la version actuellement activée avec exec_command skill=<nom> ;
Exécution d'une action représentative à faible risque ; en cas d'échec, enregistrement de la cause réelle.

skill_package validate vérifie si le package peut être installé légalement ; le lint de ce skill vérifie la qualité de création et la portabilité des skills propriétaires. Les deux ne sont pas interchangeables.

Variables d'environnement

Ce skill lui-même n'a pas besoin de variables d'environnement. Il exige que le skill cible qu'il crée déclare ses propres variables métier, et que l'hôte d'exécution les injecte dans le sous-processus actuel.

Critères de complétion

Un skill n'est considéré comme complet que si toutes les conditions suivantes sont remplies :

La description déclenche de manière stable et le périmètre est clair ;
Le noyau portable ne dépend pas de répertoires privés d'AgentDock ou de paramètres d'outils ;
Les scripts du package peuvent être exécutés depuis la racine du skill avec des chemins relatifs ;
skill-authoring lint retourne portable=true, les avertissements ont été traités un par un ;
Les vérifications de sécurité, les tests et skill_package validate sont réussis ;
La nouvelle version est installée et activée ;
agentdock_context et skill:// lisent la nouvelle version ;
La vérification réelle en lecture seule de la version actuellement activée est réussie ;
Pas de secrets, d'état privé d'appareil ou de retour d'ancienne architecture.

uvwt/agentdock

Qu'est-ce que agentdock ?

Demander à votre IA préférée

Documentation