How to Integrate dart_skills_lint into Automated Dart Test Suites

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 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 under dev_dependencies:

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.

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 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:

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:

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 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}