rundesk-ai/rundesk-cli

Rédaction de compétences

Réutiliser le propriétaire existant

Inspectez les catalogues de compétences existants avant de créer un package. Pour un travail dans un dépôt, parcourez le catalogue cible et tous les catalogues sources pertinents dans l'espace de travail autorisé. Pour un travail dans la bibliothèque live autorisée, utilisez le catalogue et les listes de compétences de Rundesk ; n'ouvrez pas la bibliothèque live pour contourner la limite d'accès de la tâche. Lisez les descriptions des correspondances plausibles, puis leurs corps et les références pertinentes avant de décider.

Étendez le propriétaire existant lorsque la capacité demandée partage son intention utilisateur, son flux de travail et son autorité. Ajoutez-y un script de support, une référence ou un test plutôt que de créer une seconde surface de routage. Créez une nouvelle compétence uniquement lorsque la capacité a besoin d'un routage, d'un jugement, d'une autorité ou d'une preuve distincts ; documentez cette distinction afin qu'un nom proche ne soit pas considéré comme une justification en soi.

Choisir l'artefact

• Une compétence est la limite d'instruction : quand agir, quel jugement appliquer, quelle procédure suivre et comment prouver le résultat.
• Un script de workflow est le mécanisme déterministe pour une transformation, validation ou orchestration locale répétée.
• Une intégration ajoute une limite de service externe : identifiants, comptes, pannes réseau, autorisations ou effets distants.

Conservez l'automatisation ponctuelle dans son projet et la commande répétée privée d'un agent dans la zone de scripts de cet agent. Empaquetez un script dans une compétence uniquement lorsque les tours futurs auront besoin de routage ou de jugement pour l'utiliser. Ne remplacez pas le code déterministe par de la prose qu'un agent doit réinterpréter.

Lisez Scripts de workflow réutilisables avant de livrer un script réutilisable. Lisez aussi Intégrations de services externes lorsqu'il utilise des identifiants, profils, OAuth, un réseau ou des effets distants.

Placer en toute sécurité

Créez une compétence privée dans local uniquement lorsque la création ou l'installation en direct est autorisée. Pour un brouillon, une revue, un changement de dépôt ou un test isolé, restez dans l'espace de travail nommé ou le répertoire temporaire ; n'inspectez pas et ne modifiez pas la bibliothèque live pour découvrir où le résultat pourrait ensuite aller.

Pour une compétence privée autorisée, demandez à Rundesk la bibliothèque au lieu de la dériver de RUNDESK_HOME ou d'intégrer un chemin absolu. Remplacez le nom d'exemple :

skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"

Écrivez <bibliothèque>/local/<nom>/SKILL.md, puis accordez-la à l'agent nommé :

"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes

L'octroi devient visible au prochain tour de l'agent, pas au tour actuel. Lisez Publication d'un catalogue de compétences avant de créer une compétence pour d'autres installations ; les compétences publiées appartiennent à un dépôt de catalogue, pas à local.

Utiliser uniquement la structure nécessaire

<nom>/
├── SKILL.md          obligatoire : routage et procédure principale
├── rundesk.json      optionnel : valeurs d'environnement requises
├── scripts/          optionnel : commandes réutilisables
├── tests/            optionnel : contrats de script quand aucune zone de test du catalogue ne les possède
├── references/       optionnel : détail chargé conditionnellement
└── assets/           optionnel : matériel copié ou produit

Créez les chemins optionnels uniquement avec du contenu. Omettre le README, le changelog, le guide d'installation et l'historique de création.

Écrire le routage en premier

Le frontmatter contient uniquement name et description.

• Faites correspondre name au répertoire. Utilisez au maximum 64 lettres minuscules, chiffres et tirets simples.
• Routez par intention utilisateur, y compris les demandes indirectes qui peuvent ne pas nommer la compétence. Commencez par Utiliser quand, Appliquer quand ou un langage d'applicabilité équivalent ; les phrases d'invite ne sont pas des déclencheurs.
• Visez deux phrases courtes : l'applicabilité, puis le workflow spécialisé ou les connaissances fournies. Ajoutez Ne pas utiliser uniquement pour un quasi-détour probable. Incluez uniquement les concepts nécessaires au routage avant le chargement du corps. Omettez les étapes, tests, affirmations d'avantages et détails d'implémentation ; ne nommez un type de fichier, outil ou format que lorsqu'il détermine si la compétence doit se déclencher.
• Utilisez la description la plus courte qui route encore correctement ; 1 024 caractères est un plafond, pas un objectif. Mettez-y chaque déclencheur car chaque porteur paie pour cela à chaque tour et le corps est indisponible tant que le routage n'a pas réussi.

# Mauvais : intègre des détails d'implémentation et de vérification qui ne peuvent pas aider au routage.
description: Utiliser lors de la création de notes de version. Il lit l'historique Git, écrit en Markdown, regroupe les commits, vérifie les liens, exécute la validation et produit des versions internes et publiques concises avec un formatage précis.

# Bon : indique l'intention, le jugement fourni et la limite la plus proche uniquement.
description: Utiliser lors de la préparation de notes de version à partir de modifications de dépôt livrées. Il fournit un workflow axé sur le public, ancré dans un historique vérifié. Ne pas utiliser pour des plans non publiés.

Conserver uniquement des conseils comportementaux

Utilisez des étapes impératives dans l'ordre d'exécution. Supposez que le lecteur peut raisonner, éditer et utiliser des outils ordinaires. Ne conservez une phrase que lorsqu'elle change l'exécution, empêche un échec probable ou achemine les détails nécessaires.

• Gardez la procédure principale, une bonne valeur par défaut et les pièges non évidents dans SKILL.md.
• Utilisez des commandes exactes pour les opérations fragiles ; utilisez un jugement concis là où plusieurs approches fonctionnent.
• Expliquez l'échec qu'une contrainte empêche au lieu d'ajouter une emphase inexpliquée.
• Introduisez chaque référence avec quand la lire. Gardez une seule source de vérité ; liez plutôt que de reformuler.
• Supprimez le contexte, l'historique du processus, les affirmations datées et les règles déjà chargées ailleurs.
• Distinguez les contrats observés des valeurs par défaut recommandées. Sourcez les contraintes techniques et enseignez les vrais pièges comme symptôme, cause, remplacement et preuve observable.

Gardez SKILL.md sous 500 lignes ; déplacez les détails conditionnels d'un niveau dans des références liées.

Budget de contexte

Partie	Coût en tokens	Conserver là
description	chaque tour	déclencheur le plus court et complet
SKILL.md	après routage	procédure principale, valeurs par défaut, pièges
references/	à la lecture	détails conditionnels et exemples plus volumineux
scripts/	la sortie entre dans le contexte	travail déterministe avec sortie limitée
tests/	validation uniquement	contrats exécutables et cas limites
assets/	à l'utilisation	modèles et matériel de sortie

Préférez les exemples courts. Limitez la sortie du script à ce dont la prochaine décision a besoin.

Prouver l'ensemble de la compétence

1. Validez le nom du répertoire, le nom du frontmatter, la syntaxe de la description et les limites.

2. Lorsqu'un octroi est nécessaire, appliquez-le et vérifiez le tour suivant :

   "$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT"
   "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT"
   

3. Exécutez la matrice des cas limites appartenant aux références et le point d'entrée exécutable direct de chaque script.

4. Dans différents tours frais, essayez une demande directe, une demande indirecte et un quasi-détour proche. Confirmez que le corps et les références requises se chargent avant le travail ; corrigez le routage par catégorie, pas par des phrases d'invite copiées.

5. Pour une compétence substantielle, comparez la même tâche avec une ligne de base fraîche sans la compétence. Ensuite, faites-la utiliser par un agent de test séparé sans l'implémentation attendue. Examinez les artefacts et les commandes directement ; le résumé de l'agent n'est pas une preuve. Supprimez les conseils qui n'apportent aucune amélioration matérielle.

6. Examinez la rédaction générée séparément de l'exactitude exécutable : précision du routage, ordre d'exécution, jugement utile, concision, duplication et discipline des références. Les tests de script verts ne prouvent pas la qualité de la rédaction. Sourcez ou observez les promesses factuelles ; testez les affirmations exécutables et affinez les vérités partielles. Contestez les affirmations sémantiques avec un contre-exemple adversarial qui préserve les agrégats pratiques tout en changeant la relation ou le résultat réel—les vérifications de mutation ne peuvent pas réparer un oracle de test erroné. Examinez l'ensemble de l'interface, y compris le succès vide, les preuves en double et chaque section de sortie dépendante des données.