La question « DeepSeek Harness Skills : projet ou global ? » ne se résout pas seulement par le nombre de projets. Elle dépend surtout de trois éléments : qui peut modifier le fichier, quels chemins il suppose et quels agents doivent l’exécuter.

Un Skill peut contenir des consignes, des références et des scripts associés. Il influence donc le comportement de l’agent, notamment ses choix d’outils, son ordre d’exécution et les fichiers qu’il consulte. Le traiter comme un simple fichier Markdown est une erreur de gouvernance.

Le fournisseur local de DeepSeek Harness distingue plusieurs familles de racines : les racines du projet, les répertoires personnalisés, le répertoire utilisateur de DeepSeek Harness et le répertoire partagé des agents. Le code officiel prévoit notamment les chemins projet .dsh/skills et .agents/skills, puis les racines utilisateur sous DSH_HOME/skills et DSH_AGENTS_HOME/skills. Les répertoires personnalisés peuvent être insérés entre les racines projet et utilisateur. Le catalogue officiel de configuration et le fournisseur de fichiers Skills documentent ces possibilités.

La conséquence pour votre décision est simple :

• Un Skill dépend du dépôt, de ses scripts ou de sa chaîne de tests : placez-le au niveau du projet.
• Un Skill reste valable dans plusieurs dépôts sans chemin interne ni outil privé : le niveau utilisateur est acceptable.
• Un Skill doit être identique pour plusieurs personnes ou exécutants : utilisez une source partagée versionnée.
• Un environnement distant doit être recréé automatiquement : livrez le Skill avec l’image, l’initialisation ou l’artefact de l’environnement.

Le mauvais choix n’est pas seulement une question de rangement. Il peut produire un agent qui applique une règle obsolète, consulte un mauvais dossier ou exécute une commande prévue pour une autre équipe.

Pour un seul projet, le choix le plus robuste est de faire voyager le Skill avec le code. Un projet audio peut ainsi conserver ses règles de traitement des pistes, ses conventions de nommage et ses scripts de rendu. Un projet vidéo peut imposer une séquence précise pour les proxies, les exports et la vérification des codecs. Un dépôt de design peut intégrer ses règles de génération d’assets et de contrôle des fichiers lourds.

Cette proximité apporte quatre bénéfices concrets :

• le Skill évolue dans le même historique que le code ;
• une branche peut tester une nouvelle procédure sans modifier les autres projets ;
• une revue de code peut contrôler les consignes et les scripts associés ;
• la récupération du dépôt suffit à reconstruire une partie du comportement de l’agent.

Le format attendu peut être un fichier Markdown autonome ou un répertoire contenant SKILL.md. Le fournisseur officiel sait découvrir une entrée Markdown directement dans une racine, ou un sous-répertoire dont le fichier principal porte le nom SKILL.md. Le code limite aussi la surveillance d’un Skill en répertoire à cette structure : un changement situé au niveau du fichier principal est détectable, alors qu’un fichier profondément imbriqué ne déclenche pas nécessairement la même invalidation. La logique officielle de découverte et de surveillance précise cette règle.

Ne copiez toutefois pas aveuglément tout votre environnement local dans le dépôt. Vérifiez au minimum :

• les chemins absolus vers vos scripts ;
• les noms d’exécutables propres à votre Mac ;
• les variables d’environnement ;
• les références à des comptes, jetons ou fichiers privés ;
• les commandes qui supposent une application graphique ouverte.

Un Skill versionné est reproductible, mais il devient aussi visible par toute personne ayant accès au dépôt. Les identifiants doivent rester dans l’environnement d’exécution ou dans un mécanisme de secrets séparé. La documentation officielle de développement recommande également de ne jamais committer une clé réelle dans le dépôt. Voir les règles de développement et de gestion des credentials.

Pour ce profil, le niveau projet est donc le choix par défaut. Le niveau global ne doit servir qu’à des aides personnelles qui ne modifient pas les règles du dépôt.

Le répertoire global est pratique lorsque vous passez régulièrement d’un dépôt à l’autre. Vous évitez les copies manuelles et une correction peut être disponible partout après une seule mise à jour. C’est pertinent pour un Skill qui explique une méthode de diagnostic, une convention personnelle de revue ou une procédure générale de génération de documentation.

Le niveau utilisateur peut être défini via DSH_HOME, dont la valeur par défaut documentée est ~/.dsh. Pour les Skills partagés entre plusieurs outils d’agents, le fournisseur prévoit aussi DSH_AGENTS_HOME, par défaut ~/.agents. Les deux racines utilisateur sont examinées séparément par le fournisseur de fichiers. Les variables et racines documentées doivent toutefois être vérifiées dans la version installée avant toute automatisation.

Mais cette commodité crée trois coûts souvent sous-estimés.

Premier coût : l’invocation involontaire. Un Skill global peut apparaître dans un projet où il n’a aucun rôle. Une procédure prévue pour une chaîne audio peut influencer une demande de développement web. Plus le nom et la description sont larges, plus le risque de sélection hors contexte augmente.

Deuxième coût : la dérive de version. Vous corrigez le Skill pour le projet A, puis le projet B reçoit immédiatement la nouvelle consigne. Si le Skill modifie une commande, une convention de test ou une règle de validation, vous venez de changer plusieurs environnements sans revue par projet.

Troisième coût : l’impact d’une erreur. Une mauvaise instruction globale ne reste pas confinée à un dépôt. Elle peut demander une commande indisponible, lire un chemin non autorisé ou supposer une structure de fichiers qui n’existe pas.

Pour éviter ces effets, placez au niveau utilisateur uniquement les capacités qui satisfont simultanément ces conditions :

• aucune dépendance à un chemin de dépôt ;
• aucune référence à une commande interne ;
• aucun accès à un secret propre à une équipe ;
• comportement acceptable dans tous vos projets ;
• procédure de retour arrière connue.

Si une seule condition échoue, revenez au niveau projet.

Un même Skill peut-il être utilisé par plusieurs projets ? Oui, mais le partage doit être intentionnel. Utilisez le niveau utilisateur pour une capacité personnelle vraiment transversale. Pour une règle d’équipe, préférez une source commune versionnée, car le global de chaque poste n’offre pas à lui seul une preuve de version identique.

Pour une équipe de développement, la solution la plus équilibrée est une architecture à deux couches :

1. le dépôt contient les Skills propres au projet ;
2. une source partagée contient les Skills communs approuvés ;
3. le projet référence ou synchronise une version précise de cette source ;
4. le répertoire partagé distribué aux utilisateurs reste en lecture seule.

Cette organisation sépare la responsabilité éditoriale. Le responsable du projet maintient les règles liées au code. L’équipe plateforme ou le groupe désigné maintient les Skills transversaux. Chaque modification importante peut recevoir un identifiant de version, une note de changement et une procédure de retour arrière.

Le point important n’est pas seulement de partager un dossier. Il faut partager une version. Un simple répertoire monté depuis un emplacement réseau crée une dépendance au réseau, aux permissions et à la disponibilité du service. Un poste hors ligne peut découvrir un Skill différent, incomplet ou ancien selon le moment où la synchronisation a échoué.

Une bonne procédure d’équipe suit cette séquence :

1. développer le Skill dans une branche dédiée ;
2. exécuter une tâche de référence sur un projet isolé ;
3. vérifier que SKILL.md ne contient ni secret ni chemin local ;
4. publier une version identifiée dans la source commune ;
5. mettre à jour la référence du projet ;
6. exécuter les tests de découverte et d’invocation ;
7. conserver la version précédente pour le retour arrière ;
8. inscrire le changement dans le journal de livraison.

Le risque principal est la collision de noms. Lorsque deux racines exposent un Skill portant le même identifiant, la priorité de la racine devient une règle opérationnelle. Le fournisseur officiel attribue un rang aux racines projet, personnalisées et utilisateur ; le détail exact doit donc être vérifié dans la version installée avant de bâtir une politique de nommage. Le code source des rangs et des racines est la référence à contrôler.

Dans la pratique, évitez les noms génériques comme review, build ou media si plusieurs équipes peuvent fournir leur propre variante. Préférez un préfixe de domaine ou de produit, puis documentez la source autorisée.

Un environnement distant ne doit pas dépendre du répertoire personnel de la personne qui l’a préparé. Si vous exécutez DeepSeek Harness sur un Mac distant, dans une tâche continue ou dans une file d’agents, le Skill doit être livré avec l’environnement d’exécution.

Le minimum à vérifier est le suivant :

• le chemin DSH_HOME est défini de manière déterministe ;
• le répertoire de Skills existe avant le démarrage de l’agent ;
• le compte d’exécution possède un accès en lecture ;
• la version livrée est enregistrée ;
• le redémarrage ne remplace pas le dossier par un volume vide ;
• chaque groupe d’exécution ne voit que les Skills autorisés.

Le catalogue officiel indique que le fournisseur peut surveiller les racines locales. La surveillance est activée par défaut dans le schéma du fournisseur, tandis que l’utilisation du mode de scrutation est désactivée par défaut. Le fournisseur prévoit aussi une limite de 128 projets distincts conservés dans la surveillance active, ainsi qu’une option pour suivre les liens symboliques. Ces valeurs et comportements appartiennent au code de la version examinée ; ils doivent être revalidés après une mise à jour majeure. Les paramètres officiels du fournisseur de fichiers constituent la source à comparer lors de chaque changement de version.

Pourquoi DeepSeek Harness ne voit-il pas un Skill nouvellement ajouté ? Commencez par le chemin réellement utilisé par la session, pas par celui affiché dans votre terminal. Vérifiez ensuite que le fichier se trouve dans une racine configurée, que son nom est exactement SKILL.md lorsqu’il est placé dans un dossier de Skill, et que son en-tête respecte le format attendu. Si la surveillance a été désactivée, si le répertoire distant n’est pas persistant ou si la session utilise une autre valeur de DSH_HOME, un redémarrage peut donner l’impression que le Skill a disparu.

Pour un déploiement contrôlé, testez toujours deux états : découverte à froid après création de l’environnement, puis découverte après redémarrage. Une seule vérification pendant la session initiale ne prouve pas que la livraison est reproductible.

Un Skill doit être traité comme une instruction ayant un effet sur l’agent. Dans un environnement sensible, le répertoire global ne devrait donc pas être librement modifiable par tous les utilisateurs ou processus.

Contrôlez au minimum :

• le propriétaire du dossier ;
• les droits d’écriture ;
• la provenance du Skill ;
• la branche ou version approuvée ;
• les scripts appelés par SKILL.md ;
• la destination réelle des liens symboliques ;
• la possibilité pour un projet de remplacer un Skill d’un niveau supérieur.

Les liens symboliques peuvent réduire les copies, mais ils déplacent le problème vers la confiance dans la cible. Le fournisseur officiel expose watchFollowSymlinks, activé par défaut dans le schéma actuel. Cela signifie qu’un lien peut devenir une dépendance invisible vers un autre volume, un répertoire partagé ou un emplacement modifiable par un autre compte. La définition officielle des options de surveillance doit être relue après toute mise à jour.

Dans une équipe soumise à des exigences de séparation, préférez une copie ou un artefact immuable à un lien symbolique traversant une frontière de confiance. Si vous utilisez malgré tout un lien, vérifiez sa cible pendant l’installation et après chaque restauration. Refusez les cibles situées dans un dossier temporaire, un partage non contrôlé ou un répertoire d’utilisateur non audité.

Utilisez cette liste de décision avant de créer votre premier répertoire :

• Si le Skill mentionne le dépôt, ses tests, ses scripts ou ses chemins internes, choisissez le niveau projet.
• Si le Skill est personnel, indépendant du dépôt et sûr dans tous vos environnements, choisissez le niveau utilisateur.
• Si plusieurs personnes doivent obtenir exactement la même version, choisissez une source partagée versionnée.
• Si le Skill est commun mais que le projet doit pouvoir revenir en arrière, choisissez projet + source partagée approuvée.
• Si l’environnement est distant ou recréé automatiquement, incluez le Skill dans l’image, l’initialisation ou l’artefact livré.
• Si le Skill traverse une frontière de confiance, désactivez l’écriture globale et limitez les liens symboliques.
• Si vous ne pouvez pas expliquer qui valide la prochaine modification, ne placez pas ce Skill dans un répertoire global.

Pour transformer cette décision en contrôle d’acceptation, cochez les éléments suivants avant la mise en service :

• [ ] le chemin effectif de DSH_HOME ou du répertoire personnalisé est consigné ;
• [ ] la version du Skill et sa source sont identifiées ;
• [ ] le fichier SKILL.md est découvert dans un projet propre ;
• [ ] le Skill se charge uniquement pour la tâche prévue ;
• [ ] un second projet ne reçoit pas de consigne indésirable ;
• [ ] le changement du fichier principal est détecté lorsque la surveillance est activée ;
• [ ] le Skill reste disponible après redémarrage ;
• [ ] le retour à la version précédente a été testé ;
• [ ] les permissions et la cible des liens symboliques sont vérifiées ;
• [ ] aucun secret, chemin local sensible ou identifiant privé n’est présent.

Après le choix, réalisez une tâche de validation identique dans deux projets différents. Confirmez que le Skill attendu est découvert, qu’il se charge lorsqu’il est pertinent, que son fichier SKILL.md est lisible et qu’aucune consigne ne se propage dans l’autre projet. Pour une équipe, consignez aussi la version, le chemin, le compte d’exécution et le résultat après redémarrage.

Le stockage manuel sur plusieurs postes présente rapidement des défauts : versions différentes, synchronisation incertaine, répertoires personnels non persistants et diagnostic difficile après un redémarrage. Un environnement cloud générique ajoute souvent une autre couche de variation : système d’exploitation différent, outils graphiques absents, chemins incompatibles et restauration incomplète des fichiers d’agent.

Pour les tâches audio, vidéo, design ou développement nécessitant un environnement macOS stable, la location d’un Mac auprès de KVMNODE peut être plus cohérente qu’un montage improvisé sur plusieurs machines. Vous pouvez alors intégrer le dossier de Skills, sa version et le test de reprise dans la procédure de livraison, au lieu de demander à chaque utilisateur de maintenir son propre répertoire global.

Si vous envisagez cette voie, commencez par examiner les options de Mac distant de KVMNODE, puis utilisez une configuration adaptée à votre zone de travail, comme un Mac disponible pour la région US East ou la région US West. L’objectif n’est pas de louer un Mac pour chaque usage : un achat local reste préférable pour une charge lourde permanente ou un besoin d’interface physique. En revanche, pour une période de test, une validation d’agent ou un pool d’exécution temporaire, une livraison contrôlée réduit les différences entre postes et rend l’emplacement des Skills vérifiable.