Validation des compétences avec dart_skills_lint

Contenus

Utilisation pour les agents (CLI)
Configuration pour les développeurs Dart
Création de règles personnalisées
Flux de travail : Validation des compétences
Référence de spécification

Utilisation pour les agents (CLI)

Utilisez le CLI dart_skills_lint pour valider les compétences. Choisissez le flux de travail approprié en fonction de votre environnement :

Scénario A : Le package se trouve dans les dépendances de votre projet

Utilisez cette méthode si vous travaillez dans un projet qui a dart_skills_lint listé dans pubspec.yaml. Exécutez :

dart run dart_skills_lint -d .agents/skills

Scénario B : Le package est activé globalement

Utilisez cette méthode si vous souhaitez valider les compétences sur plusieurs projets sans ajouter de dépendance à chacun. Exécutez :

dart pub global run dart_skills_lint -d .agents/skills

Drapeaux courants

-d, --skills-directory: Spécifie un répertoire racine contenant des sous-dossiers de compétences à valider. Peut être passé plusieurs fois.
-s, --skill: Spécifie un répertoire de compétence individuel à valider directement. Peut être passé plusieurs fois.
-q, --quiet: Masque les sorties de validation non-erreur.
-w, --print-warnings: Active l'impression des messages d'avertissement.
--fast-fail: Arrête l'exécution immédiatement en cas d'erreur.
--ignore-config: Ignore entièrement le fichier de configuration YAML.

Configuration pour les développeurs Dart

Configurez la validation dans votre projet Dart :

Ajoutez dart_skills_lint à votre pubspec.yaml comme dev_dependency :
```
dev_dependencies:
  dart_skills_lint: ^0.2.0
```

Intégrez le linter dans vos tests automatisés en important le package et en appelant validateSkills. Cela garantit que vos compétences sont automatiquement validées chaque fois que vous exécutez dart test.

Exemple test/lint_skills_test.dart :

import 'dart:async';
import 'package:dart_skills_lint/dart_skills_lint.dart';
import 'package:logging/logging.dart';
import 'package:test/test.dart';

void main() {
  test('Run skills linter', () async {
    // Enable logging to see detailed validation errors in test output.
    final Level oldLevel = Logger.root.level;
    Logger.root.level = Level.ALL;
    final StreamSubscription<LogRecord> subscription =
        Logger.root.onRecord.listen((record) => print(record.message));

    try {
      final isValid = await validateSkills(
        skillDirPaths: ['.agents/skills'],
        resolvedRules: {
          'check-relative-paths': AnalysisSeverity.error,
          'check-absolute-paths': AnalysisSeverity.error,
          'check-trailing-whitespace': AnalysisSeverity.error,
        },
      );
      expect(isValid, isTrue, reason: 'Skills validation failed. See above for details.');
    } finally {
      Logger.root.level = oldLevel;
      await subscription.cancel();
    }
  });
}

(Optionnel) Créez un fichier de configuration dart_skills_lint.yaml à la racine de votre projet pour personnaliser les règles et répertoires du CLI : Remarque : Si vous utilisez validateSkills directement dans les tests, le fichier dart_skills_lint.yaml est ignoré par défaut, et vous devez transmettre la configuration par programmation si nécessaire.
```
dart_skills_lint:
  rules:
    check-relative-paths: error
    check-absolute-paths: error
  directories:
    - path: ".agents/skills"
```

Intégration initiale dans un référentiel

Lors de l'ajout de dart_skills_lint à un référentiel pour la première fois, suivez ces bonnes pratiques basées sur l'intégration du monde réel :

1. Gestion des dépendances d'espace de travail

Si votre référentiel est un espace de travail avec plusieurs packages :

Isolez la dépendance : Ajoutez dart_skills_lint au package spécifique qui gère les outils ou les tests (par exemple, tool/pubspec.yaml) plutôt qu'au pubspec.yaml racine, à moins que ce soit strictement nécessaire au niveau racine.
Gardez les hashes en synchronisation : Si vous devez l'ajouter à plusieurs fichiers pubspec.yaml (par exemple, racine et package d'outils), assurez-vous que la ref (hash de commit) est identique pour éviter les conflits de résolution.

2. Emplacement du fichier de configuration

Placez dart_skills_lint.yaml dans le répertoire à partir duquel vous prévoyez d'exécuter la commande (par exemple, à l'intérieur de tool/ si c'est là que se trouve votre configuration).
Mettez à jour les chemins relatifs : Assurez-vous que les entrées path du fichier de configuration sont relatives à ce répertoire (par exemple, ../.agents/skills si vous exécutez depuis tool/ pour cibler un dossier à la racine du référentiel).

3. Génération d'une base de référence

Si vous intégrez le linter dans un référentiel avec des compétences existantes qui peuvent avoir des erreurs héritées ou des faux positifs :

Utilisez la fonctionnalité de base de référence pour ignorer les problèmes existants et recommencer avec une exécution propre.

Exécutez :

dart run dart_skills_lint:cli --skills-directory=.agents/skills --generate-baseline

Cela créera un fichier dart_skills_lint_ignore.json.
Remarque sur les faux positifs : Le linter évalue actuellement les liens à l'intérieur des blocs de code markdown. Si votre documentation de compétence inclut des exemples avec des liens ou des images d'espace réservé, ils peuvent être signalés comme cassés. Utilisez le fichier de base de référence pour ignorer ces faux positifs spécifiques.

Création de règles personnalisées

Pour créer des règles personnalisées, étendez la classe SkillRule et passez-les à validateSkills.

Exemple :

import 'package:dart_skills_lint/dart_skills_lint.dart';

class MyCustomRule extends SkillRule {
  @override
  final String name = 'my-custom-rule';

  @override
  final AnalysisSeverity severity = AnalysisSeverity.warning;

  @override
  Future<List<ValidationError>> validate(SkillContext context) async {
    final errors = <ValidationError>[];
    final yaml = context.parsedYaml;
    if (yaml == null) return errors;

    if (yaml['metadata']?['deprecated'] == true) {
      errors.add(ValidationError(
        ruleId: name,
        severity: severity,
        file: 'SKILL.md',
        message: 'This skill is marked as deprecated.',
      ));
    }
    return errors;
  }
}

Utilisez-la dans votre test :

await validateSkills(
  skillDirPaths: ['.agents/skills'],
  customRules: [MyCustomRule()],
);

Flux de travail : Validation des compétences

Suivez ce flux de travail pour valider les compétences :

Exécutez le validateur : Exécutez le linter sur votre répertoire de compétences.
```
dart run dart_skills_lint -d .agents/skills
```
Vérifiez les erreurs : Vérifiez la sortie pour toute erreur ou avertissement.
Corrigez les violations : Modifiez le SKILL.md ou la structure de répertoire pour résoudre les problèmes.
Vérifiez : Réexécutez le validateur pour vous assurer que toutes les vérifications passent.

Progression des tâches

[ ] Exécutez le validateur
[ ] Vérifiez les erreurs
[ ] Corrigez les violations
[ ] Vérifiez une exécution propre

Référence de spécification

<details> <summary>Afficher les contraintes de spécification des compétences</summary>

Structure des répertoires et des fichiers

Fichier SKILL.md obligatoire à la racine du dossier de compétence.
Les répertoires commençant par un point . (par exemple, .dart_tool) sont ignorés.

Métadonnées (préambule YAML)

Champs obligatoires : name et description.

Contraintes de champs

Name : Maximum 64 caractères, alphanumériques minuscules et traits d'union uniquement. Doit correspondre au nom du répertoire parent.
Description : Maximum 1024 caractères.
Compatibility : Maximum 500 caractères. </details>