sdd-full 4.6.1 → 4.8.0

package/skills/flutter-skills/tool/dart_skills_lint/lib/src/validator.dart

@@ -0,0 +1,238 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+import 'package:yaml/yaml.dart';
+
+import 'models/analysis_severity.dart';
+import 'models/check_type.dart';
+import 'models/skill_context.dart';
+import 'models/skill_rule.dart';
+import 'models/validation_error.dart';
+import 'rule_registry.dart';
+
+const _dirStructureUrl = 'https://agentskills.io/specification#directory-structure';
+
+final _log = Logger('dart_skills_lint');
+
+/// Validates agent skill directories against the Agent Skills specification.
+class Validator {
+  Validator({Map<String, AnalysisSeverity>? ruleOverrides, List<SkillRule>? customRules})
+    : _customSeverities = ruleOverrides ?? {},
+      _rules = _buildRules(ruleOverrides ?? {}, customRules ?? []);
+  static const String _skillFileName = SkillContext.skillFileName;
+
+  /// The name of the special check for missing files or directories.
+  static const String pathDoesNotExist = 'path-does-not-exist';
+
+  /// The name of the special check for inaccessible files.
+  static const String skillFileInaccessible = 'skill-file-inaccessible';
+
+  /// The name of the special check for unexpected errors.
+  static const String unexpectedError = 'unexpected-error';
+
+  final Map<String, AnalysisSeverity> _customSeverities;
+  final List<SkillRule> _rules;
+
+  /// Returns the rules used by this validator.
+  List<SkillRule> get rules => _rules;
+
+  AnalysisSeverity _getSeverity(String name, AnalysisSeverity defaultSeverity) {
+    return _customSeverities[name] ?? defaultSeverity;
+  }
+
+  /// Validates a single skill directory.
+  ///
+  /// Scans the directory for `SKILL.md`, parses its YAML metadata, and validates
+  /// constraints like name format and field lengths using registered rules.
+  Future<ValidationResult> validate(Directory dir) async {
+    final validationErrors = <ValidationError>[];
+
+    final bool isValidDir = await _checkDirectoryStructure(dir, validationErrors);
+    if (!isValidDir) {
+      return ValidationResult(validationErrors: validationErrors);
+    }
+
+    final skillMdFile = File(p.join(dir.path, _skillFileName));
+    String content;
+    try {
+      content = await skillMdFile.readAsString();
+    } on FileSystemException catch (e) {
+      validationErrors.add(
+        ValidationError(
+          ruleId: skillFileInaccessible,
+          file: skillMdFile.path,
+          message: 'Failed to read $_skillFileName: $e',
+          severity: _getSeverity(skillFileInaccessible, AnalysisSeverity.error),
+        ),
+      );
+      return ValidationResult(validationErrors: validationErrors);
+    } catch (e) {
+      validationErrors.add(
+        ValidationError(
+          ruleId: unexpectedError,
+          file: skillMdFile.path,
+          message: 'Unexpected error reading $_skillFileName: $e',
+          severity: _getSeverity(unexpectedError, AnalysisSeverity.error),
+        ),
+      );
+      return ValidationResult(validationErrors: validationErrors);
+    }
+
+    YamlMap? parsedYaml;
+    String? yamlParsingError;
+    try {
+      final RegExpMatch? match = SkillContext.skillStartRegex.firstMatch(content);
+      if (match != null) {
+        final String yamlStr = match.group(1)!;
+        final Object? doc = loadYaml(yamlStr);
+        if (doc is YamlMap) {
+          parsedYaml = doc;
+        } else {
+          yamlParsingError = 'YAML frontmatter is not a map';
+        }
+      } else {
+        yamlParsingError = 'Missing YAML metadata in $_skillFileName';
+      }
+    } catch (e) {
+      yamlParsingError = 'Failed to parse YAML: $e';
+    }
+
+    final context = SkillContext(
+      directory: dir,
+      rawContent: content,
+      parsedYaml: parsedYaml,
+      yamlParsingError: yamlParsingError,
+    );
+
+    for (final SkillRule rule in _rules) {
+      final List<ValidationError> errors = await rule.validate(context);
+      for (final error in errors) {
+        if (error.severity != rule.severity) {
+          _log.warning(
+            'Rule "${rule.name}" used severity ${error.severity} instead of defined ${rule.severity}.',
+          );
+        }
+      }
+      validationErrors.addAll(errors);
+    }
+
+    return ValidationResult(validationErrors: validationErrors, context: context);
+  }
+
+  static List<SkillRule> _buildRules(
+    Map<String, AnalysisSeverity> customSeverities,
+    List<SkillRule> customRules,
+  ) {
+    final rules = <SkillRule>[];
+    final seenNames = <String>{};
+
+    void addRule(SkillRule rule) {
+      if (rule.severity != AnalysisSeverity.disabled) {
+        if (seenNames.contains(rule.name)) {
+          throw ArgumentError('Duplicate rule name detected: ${rule.name}');
+        }
+        seenNames.add(rule.name);
+        rules.add(rule);
+      }
+    }
+
+    for (final CheckType check in RuleRegistry.allChecks) {
+      final AnalysisSeverity severity = customSeverities[check.name] ?? check.defaultSeverity;
+      final SkillRule? rule = RuleRegistry.createRule(check.name, severity);
+      if (rule != null) {
+        addRule(rule);
+      }
+    }
+
+    customRules.forEach(addRule);
+
+    return rules;
+  }
+
+  Future<bool> _checkDirectoryStructure(
+    Directory dir,
+    List<ValidationError> validationErrors,
+  ) async {
+    final AnalysisSeverity pathDoesNotExistSeverity = _getSeverity(
+      pathDoesNotExist,
+      AnalysisSeverity.error,
+    );
+
+    if (!dir.existsSync()) {
+      if (File(dir.path).existsSync()) {
+        validationErrors.add(
+          ValidationError(
+            ruleId: pathDoesNotExist,
+            file: dir.path,
+            message: 'Path is not a directory: ${dir.path} (see $_dirStructureUrl)',
+            severity: pathDoesNotExistSeverity,
+          ),
+        );
+      } else {
+        validationErrors.add(
+          ValidationError(
+            ruleId: pathDoesNotExist,
+            file: dir.path,
+            message: 'Directory does not exist: ${dir.path} (see $_dirStructureUrl)',
+            severity: pathDoesNotExistSeverity,
+          ),
+        );
+      }
+      return false;
+    }
+
+    final skillMdFile = File(p.join(dir.path, _skillFileName));
+    if (!skillMdFile.existsSync()) {
+      validationErrors.add(
+        ValidationError(
+          ruleId: pathDoesNotExist,
+          file: dir.path,
+          message: '$_skillFileName is missing in directory: ${dir.path} (see $_dirStructureUrl)',
+          severity: pathDoesNotExistSeverity,
+        ),
+      );
+      return false;
+    }
+    return true;
+  }
+}
+
+/// The result of a skill directory validation attempt.
+class ValidationResult {
+  ValidationResult({
+    this.validationErrors = const [],
+    List<String> warnings = const [],
+    this.context,
+  }) : _manualWarnings = warnings;
+
+  /// The context used during validation.
+  final SkillContext? context;
+
+  /// Whether the skill directory is valid according to the specification.
+  bool get isValid =>
+      !validationErrors.any((e) => e.severity == AnalysisSeverity.error && !e.isIgnored);
+
+  /// A list of structured validation errors found.
+  final List<ValidationError> validationErrors;
+
+  final List<String> _manualWarnings;
+
+  /// A list of error messages for failing checks (excluding ignored ones).
+  List<String> get errors => validationErrors
+      .where((e) => e.severity == AnalysisSeverity.error && !e.isIgnored)
+      .map((e) => e.message)
+      .toList();
+
+  /// A list of warning messages for suboptimal setups or recommendations.
+  List<String> get warnings => [
+    ..._manualWarnings,
+    ...validationErrors
+        .where((e) => e.severity == AnalysisSeverity.warning && !e.isIgnored)
+        .map((e) => e.message),
+  ];
+}

package/skills/flutter-skills/tool/dart_skills_lint/pubspec.yaml

@@ -0,0 +1,28 @@
+name: dart_skills_lint
+description: A static analysis linter for agent skills.
+version: 0.2.0
+resolution: workspace
+repository: https://github.com/flutter/skills
+
+environment:
+  sdk: ^3.10.8
+
+dependencies:
+  args: ^2.4.0
+  io: ^1.0.4
+  logging: ^1.2.0
+  meta: ^1.11.0
+  path: ^1.9.1
+  yaml: ^3.1.3
+  json_annotation: ^4.8.0
+
+dev_dependencies:
+  lints: ^6.0.0
+  test: ^1.24.0
+  test_process: ^2.1.1
+  json_serializable: ^6.7.0
+  build_runner: ^2.4.0
+  dart_code_linter: ^4.0.3
+
+executables:
+  dart_skills_lint: cli

package/skills/flutter-skills/tool/dart_skills_lint/skills/README.md

@@ -0,0 +1,10 @@
+# Skills shipped with dart_skills_lint
+
+The skills in this directory are shipped with the `dart_skills_lint` package.
+They are intended for users of the package to help them use it effectively.
+
+To install these skills into your IDE, you can use the [skills](https://pub.dev/packages/skills) package on pub:
+```bash
+dart pub global activate skills
+skills get
+```

package/skills/flutter-skills/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: dart-skills-lint-validation
+description: |-
+  Use this skill when you need to validate that AI agent skills meet the specification.
+  This includes generic validation of any skills for users that have Dart installed,
+  as well as integrating dart_skills_lint into a Dart project as a dev_dependency
+  to automate skill validation in tests or CI/CD.
+---
+
+# Validating Skills with dart_skills_lint
+
+## Contents
+- [Usage for Agents (CLI)](#usage-for-agents-cli)
+- [Setup for Dart Developers](#setup-for-dart-developers)
+- [Authoring Custom Rules](#authoring-custom-rules)
+- [Workflow: Validating Skills](#workflow-validating-skills)
+- [Specification Reference](#specification-reference)
+
+## Usage for Agents (CLI)
+Use the `dart_skills_lint` CLI to validate skills. Choose the appropriate workflow based on your environment:
+
+### Scenario A: The package is in your project dependencies
+Use this method if you are working within a project that has `dart_skills_lint` listed in `pubspec.yaml`.
+Run:
+```bash
+dart run dart_skills_lint -d .agents/skills
+```
+
+### Scenario B: The package is activated globally
+Use this method if you want to validate skills across multiple projects without adding a dependency to each one.
+Run:
+```bash
+dart pub global run dart_skills_lint -d .agents/skills
+```
+
+### Common Flags
+- `-d`, `--skills-directory`: Specifies a root directory containing sub-folders of skills to validate. Can be passed multiple times.
+- `-s`, `--skill`: Specifies an individual skill directory to validate directly. Can be passed multiple times.
+- `-q`, `--quiet`: Hide non-error validation output.
+- `-w`, `--print-warnings`: Enable printing of warning messages.
+- `--fast-fail`: Halt execution immediately on the error.
+- `--ignore-config`: Ignore the YAML configuration file entirely.
+
+## Setup for Dart Developers
+Setup validation in your Dart project:
+
+1. Add `dart_skills_lint` to your `pubspec.yaml` as a `dev_dependency`:
+   ```yaml
+   dev_dependencies:
+     dart_skills_lint: ^0.2.0
+   ```
+
+2. Integrate the linter into your automated tests by importing the package and calling `validateSkills`. This ensures your skills are automatically validated whenever you run `dart test`.
+
+   Example `test/lint_skills_test.dart`:
+   ```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();
+       }
+     });
+   }
+   ```
+
+3. (Optional) Create a configuration file `dart_skills_lint.yaml` in the root of your project to customize rules and directories for the CLI:
+**Note:** If you use `validateSkills` directly in tests, the `dart_skills_lint.yaml` file is ignored by default, and you should pass configuration programmatically if needed.
+   ```yaml
+   dart_skills_lint:
+     rules:
+       check-relative-paths: error
+       check-absolute-paths: error
+     directories:
+       - path: ".agents/skills"
+   ```
+
+## Initial Integration in a Repository
+
+When adding `dart_skills_lint` to a repository for the first time, follow these best practices based on real-world integration:
+
+### 1. Workspace Dependency Management
+If your repository is a workspace with multiple packages:
+- **Isolate the dependency**: Add `dart_skills_lint` to the specific package that handles tooling or tests (e.g., `tool/pubspec.yaml`) rather than the root `pubspec.yaml`, unless it is strictly needed at the root level.
+- **Keep hashes in sync**: If you must add it to multiple `pubspec.yaml` files (e.g., root and a tool package), ensure the `ref` (commit hash) is identical to avoid resolution conflicts.
+
+### 2. Configuration File Location
+- Place `dart_skills_lint.yaml` in the directory from which you plan to run the command (e.g., inside `tool/` if that's where your setup lives).
+- **Update relative paths**: Ensure the `path` entries in the config file are relative to that directory (e.g., `../.agents/skills` if running from `tool/` to target a folder in the repository root).
+
+### 3. Generating a Baseline
+If you are integrating the linter into a repository with existing skills that may have legacy errors or false positives:
+- Use the baseline feature to ignore existing issues and start with a clean run.
+- Run:
+  ```bash
+  dart run dart_skills_lint:cli --skills-directory=.agents/skills --generate-baseline
+  ```
+- This will create a `dart_skills_lint_ignore.json` file.
+- **Note on False Positives**: The linter currently evaluates links inside markdown code blocks. If your skill documentation includes examples with placeholder links or images, they might be flagged as broken. Use the baseline file to ignore these specific false positives.
+
+## Authoring Custom Rules
+To author custom rules, extend the `SkillRule` class and pass them to `validateSkills`.
+
+Example:
+```dart
+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;
+  }
+}
+```
+
+Use it in your test:
+```dart
+await validateSkills(
+  skillDirPaths: ['.agents/skills'],
+  customRules: [MyCustomRule()],
+);
+```
+
+## Workflow: Validating Skills
+Follow this workflow to validate skills:
+
+1. **Run the validator**: Execute the linter on your skills directory.
+   ```bash
+   dart run dart_skills_lint -d .agents/skills
+   ```
+2. **Review errors**: Check the output for any errors or warnings.
+3. **Fix violations**: Edit the `SKILL.md` or directory structure to resolve issues.
+4. **Verify**: Re-run the validator to ensure all checks pass.
+
+### Task Progress
+- [ ] Run validator
+- [ ] Review errors
+- [ ] Fix violations
+- [ ] Verify clean run
+
+## Specification Reference
+<details>
+<summary>View Skill Specification Constraints</summary>
+
+### Directory and File Structure
+- Mandatory `SKILL.md` file at the root of the skill folder.
+- Directories starting with a dot `.` (e.g., `.dart_tool`) are ignored.
+
+### Metadata (YAML Frontmatter)
+- Required fields: `name` and `description`.
+
+### Field Constraints
+- **Name**: Max 64 characters, lowercase alphanumeric and hyphens only. Must match the parent directory name.
+- **Description**: Max 1024 characters.
+- **Compatibility**: Max 500 characters.
+</details>

package/skills/flutter-skills/tool/dart_skills_lint/skills-lock.json

@@ -0,0 +1,75 @@
+{
+  "version": 1,
+  "skills": {
+    "dart-best-practices": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-best-practices/SKILL.md",
+      "computedHash": "1f529bd357368f67621de2c25531f69e16f726ecbe0071aabbf47b6d7b2a16c4"
+    },
+    "dart-checks-migration": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-checks-migration/SKILL.md",
+      "computedHash": "15592bf08008e2a37da5d1f4dc6b99dae01ce0db1ec7127f97cdfac3d6bcfb5d"
+    },
+    "dart-cli-app-best-practices": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-cli-app-best-practices/SKILL.md",
+      "computedHash": "83487d2341e4b692d180fe6c9fc402706a5707aba227424db016182006cfdf30"
+    },
+    "dart-doc-validation": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-doc-validation/SKILL.md",
+      "computedHash": "acc150afe3406de17059f9215fa009ffeb1b7c0815f903c2af303380e90055c4"
+    },
+    "dart-long-lines": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-long-lines/SKILL.md",
+      "computedHash": "db6543389e683823446c7ee27fb162f219cc47f209809b9fd79b012bdb944991"
+    },
+    "dart-matcher-best-practices": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-matcher-best-practices/SKILL.md",
+      "computedHash": "99a200dca8676e865b97a81abe40e8f9e2b9afdbd0f82845c1e3c8dd7eae007b"
+    },
+    "dart-modern-features": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-modern-features/SKILL.md",
+      "computedHash": "3148ee2c96c296593d3cd704d4bd99af25c84237a40c07acad5696328555907a"
+    },
+    "dart-package-maintenance": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-package-maintenance/SKILL.md",
+      "computedHash": "92efdb1b873eec4e0bcb61ade541b954eee347c3ddd70c27ba22c982c318d7e6"
+    },
+    "dart-test-coverage": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-test-coverage/SKILL.md",
+      "computedHash": "b52e0f0203181a5b6eeb5ea202f7509ab8380c53448411b84e1f84696436dfdb"
+    },
+    "dart-test-fundamentals": {
+      "source": "kevmoo/dash_skills",
+      "sourceType": "github",
+      "skillPath": ".agent/skills/dart-test-fundamentals/SKILL.md",
+      "computedHash": "0d6e877c3575136909afa4f9daa82ed48c713a3052f8e211b2476043b0438bf7"
+    },
+    "grill-me": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "computedHash": "784f0dbb7403b0f00324bce9a112f715342777a0daee7bbb7385f9c6f0a170ea"
+    },
+    "test-driven-development": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "computedHash": "126f1ebf6ccd414f42544f6e83d8cc5adb089e1108eaffb7c400701e37eecd9f"
+    }
+  }
+}