# How to Integrate dart_skills_lint into Automated Dart Test Suites

> Integrate dart_skills_lint into your Dart test suites for automated validation. Add it as a dev dependency and invoke validateSkills() in CI to ensure Agent Skills integrity.

- Repository: [Flutter/skills](https://github.com/flutter/skills)
- Tags: how-to-guide
- Published: 2026-05-09

---

**Add `dart_skills_lint` as a dev dependency and invoke `validateSkills()` inside a `dart test` file to automatically validate Agent Skills during CI runs.**

The `dart_skills_lint` package from the `flutter/skills` repository provides static analysis for Agent Skill specifications, ensuring every [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md) file complies with formatting standards and metadata requirements. Integrating this linter into your automated Dart test suites guarantees that malformed YAML front-matter, forbidden absolute paths, and trailing whitespace violations are caught before code reaches production.

## Why Embed dart_skills_lint in CI?

Embedding the linter in your continuous integration pipeline prevents broken skill definitions from landing in your repository. According to the `flutter/skills` source code, the tool validates compliance with the skill specification by checking directory structures, parsing YAML configuration, and applying configurable rules. When integrated into `dart test`, validation failures throw exceptions that automatically fail the build, blocking invalid commits.

## Step-by-Step Integration

### Add the Package Dependency

Include `dart_skills_lint` in your [`pubspec.yaml`](https://github.com/flutter/skills/blob/main/pubspec.yaml) under `dev_dependencies`:

```yaml
dev_dependencies:
  dart_skills_lint: ^0.2.0

```

Run `dart pub get` to install the package.

### Create a Validation Test File

Create a test file (e.g., `test/lint_skills_test.dart`) that imports the public API and calls `validateSkills`. This function returns a `Future<void>` that completes successfully only if all skills pass validation; otherwise, it throws detailed errors that cause the test runner to report failure.

```dart
import 'package:dart_skills_lint/dart_skills_lint.dart';
import 'package:test/test.dart';

void main() {
  test('Run skills linter', () async {
    final config = Configuration(
      directoryConfigs: [
        DirectoryConfig(
          path: '../../skills',
          rules: {},
          ignoreFile: '.agents/skills/flutter_skills_ignore.json',
        ),
      ],
    );

    await validateSkills(
      skillDirPaths: ['../../skills'],
      resolvedRules: {
        'check-relative-paths': AnalysisSeverity.error,
        'check-absolute-paths': AnalysisSeverity.error,
      },
      config: config,
    );
  });
}

```

### Configure Custom Rules (Optional)

Extend the `SkillRule` class to implement domain-specific validation logic. Pass custom rule instances via the `customRules` parameter in `validateSkills`. You may also supply a [`dart_skills_lint.yaml`](https://github.com/flutter/skills/blob/main/dart_skills_lint.yaml) configuration file, parsed by `tool/dart_skills_lint/lib/src/config_parser.dart`, to adjust settings without modifying code.

## Advanced Implementation Examples

### Validating with Custom Rules

The following example demonstrates creating a custom rule that flags deprecated skills:

```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;
  }
}

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

```

### Running via Command Line for Debugging

While automated tests use the programmatic API, you can validate skills manually using the CLI tool for local debugging:

```bash
dart run dart_skills_lint --skills-directory ./path/to/skills

```

## Core Architecture and Source Files

Understanding the implementation in `flutter/skills` helps troubleshoot integration issues:

- **`tool/dart_skills_lint/lib/src/config_parser.dart`**: Parses [`dart_skills_lint.yaml`](https://github.com/flutter/skills/blob/main/dart_skills_lint.yaml) and constructs `Configuration` objects.
- **`tool/dart_skills_lint/lib/src/validator.dart`**: Contains the core linting engine that traverses skill directories and applies rules.
- **`tool/dart_skills_lint/lib/src/rules/*.dart`**: Implements built-in validations such as `check-relative-paths` and `check-trailing-whitespace`.
- **`tool/dart_skills_lint/test/trailing_whitespace_test.dart`**: Demonstrates how the project tests its own linter, serving as a reference for your integration.

## Summary

- **Add** `dart_skills_lint` to `dev_dependencies` and run `dart pub get`.
- **Create** a test file that constructs a `Configuration` and awaits `validateSkills()`.
- **Throw** on validation errors automatically by using the standard test runner—no additional assertion logic required.
- **Extend** `SkillRule` to add custom validation logic specific to your organization's requirements.
- **Reference** [`tool/dart_skills_lint/README.md`](https://github.com/flutter/skills/blob/main/tool/dart_skills_lint/README.md) and existing tests like `metadata_validation_test.dart` for implementation patterns.

## Frequently Asked Questions

### What does dart_skills_lint validate?

The linter checks Agent Skill files for compliance with the skill specification, including valid YAML front-matter in [`SKILL.md`](https://github.com/flutter/skills/blob/main/SKILL.md), absence of trailing whitespace, relative path constraints, and forbidden absolute paths. It validates directory structures as configured in `tool/dart_skills_lint/lib/src/validator.dart`.

### Can I use dart_skills_lint without modifying my pubspec.yaml?

Yes. You can activate the package globally using `dart pub global activate dart_skills_lint` and run it via CLI. However, for automated test suite integration, adding it as a dev dependency ensures version pinning and reproducible builds across CI environments.

### How do I customize the severity of built-in rules?

Pass a `resolvedRules` map to `validateSkills` where keys are rule identifiers (e.g., `'check-relative-paths'`) and values are `AnalysisSeverity` enums (`error`, `warning`, or `info`). Alternatively, define severities in a [`dart_skills_lint.yaml`](https://github.com/flutter/skills/blob/main/dart_skills_lint.yaml) file parsed by `config_parser.dart`.

### Where can I find example tests in the repository?

The `flutter/skills` repository includes reference implementations in `tool/dart_skills_lint/test/trailing_whitespace_test.dart` and `tool/dart_skills_lint/test/metadata_validation_test.dart`. These files demonstrate how the linter exercises its own validation logic in CI, providing templates for your integration.