dart-skills-lint-integration

name	dart-skills-lint-integration
description	How to integrate, update, and configure the dart_skills_lint validation tool within a repository. Make sure to use this skill whenever the user asks to update dart_skills_lint, configure skills validation tests, fix skills linter dependency drifts, verify repository state before editing, optimize lint rules execution, or draft pull request submission commands.
metadata	{"internal":true}

Integrating and Configuring dart_skills_lint

Use this skill to verify repository state, update pinned references, manage centralized configurations, implement efficient validation test suites, and output clean pull request commands for dart_skills_lint.

Pre-Flight Repository Verification

Before initiating any modifications or executing dependency updates, ensure the repository is in a clean, safe state:

1. Run git status to confirm the repository has no active work in progress.
2. If clean, check out the primary tracking branch (e.g., main or master).
3. Fast-forward update from the remote owned by the authoritative org.
4. If post-checkout hooks report engine updates, run necessary sync utilities (such as gclient sync) to guarantee consistency before proceeding.

Dependency Management Workflow

When updating dart_skills_lint within a workspace or standalone project:

1. Locate the target pubspec.yaml defining the dependency.
2. Update the pinned Git commit reference directly in the ref field.
3. Synchronize the lockfile natively using the environment's package manager.

Example: Pinned Git Dependency

  dart_skills_lint:
    git:
      url: https://github.com/flutter/skills
      path: tool/dart_skills_lint
      ref: e4497873950727ee781fa411c1a2f624b1ec50c6

Centralized Configuration Schema

Configure rules and target paths globally via dart_skills_lint.yaml. Always define paths relative to the repository root execution context. Ensure that rules at the directory level are properly oriented within a nested rules map.

Standard Schema Implementation

dart_skills_lint:
  rules:
    check-relative-paths: error
    check-absolute-paths: error
    check-trailing-whitespace: error
  directories:
    - path: ".agents/skills"

Validation Test Implementation Patterns

To centralize rule management, load Configuration dynamically via ConfigParser.loadConfig and supply it to validateSkills.

If test suites execute under simple environments with stable execution roots, omit the skillDirPaths parameter entirely to natively inherit target paths defined within the YAML configuration.

Absolute Isolation Pattern: If test harnesses manipulate runtime execution working directories (such as CI frameworks running tests inside sub-package folders), guarantee path resilience by resolving configuration files absolutely using dynamic directory contexts (e.g., repoRoot.path). Explicitly inject absolute skillDirPaths targeting; global rules defined under rules: map unconditionally regardless of explicit target path usage.

When updating an existing validation block, explicitly audit any adjacent TODO or tracker comments. If the comment describes refactoring config loading or references issues resolved by this update, delete the comment block entirely.

Core Validation Workflow

import 'package:path/path.dart' as path;
import 'package:dart_skills_lint/dart_skills_lint.dart';

const String _configFileName = 'dart_skills_lint.yaml';

test('Validate Repository Skills', () async {
  // Use dynamic absolute resolution references to guarantee CI stability
  final Configuration config = await ConfigParser.loadConfig(
    path: path.join(repoRoot.path, 'path', 'to', _configFileName),
  );
  final bool isValid = await validateSkills(
    skillDirPaths: [skillsDirectory], // Explicit absolute targeting
    config: config,
  );
  expect(isValid, isTrue);
});

Eliminating Duplicate Overhead in Secondary Blocks

Secondary test blocks enforcing specialized custom rules without loading the shared configuration must supply target paths explicitly. To prevent duplicate execution overhead, explicitly map all default registered built-in rules to AnalysisSeverity.disabled.

test('Custom Rule Validation', () async {
  final bool isValid = await validateSkills(
    skillDirPaths: ['path/to/skills'],
    customRules: [MyCustomRule()],
    resolvedRules: {
      'check-absolute-paths': AnalysisSeverity.disabled,
      'check-relative-paths': AnalysisSeverity.disabled,
      'check-trailing-whitespace': AnalysisSeverity.disabled,
      'description-too-long': AnalysisSeverity.disabled,
      'disallowed-field': AnalysisSeverity.disabled,
      'invalid-skill-name': AnalysisSeverity.disabled,
      'valid-yaml-metadata': AnalysisSeverity.disabled,
    },
  );
  expect(isValid, isTrue);
});

Expected Final Output: Pull Request Creation Command

Conclude tasks by staging verified work on a descriptive local branch (suffixed with the date in YYYY-MM-DD format), committing the changes with a concise, standard commit message, and outputting a fully executable gh pr create command.

Discovering and Populating the Pull Request Template

To ensure formatting compliance, always look up the target repository's native pull request template before generating the submission body:

1. Locate Template: Search for template files within .github/, .github/PULL_REQUEST_TEMPLATE/, or the project root. Common filenames include PULL_REQUEST_TEMPLATE.md or pull_request_template.md.
2. Extract Structure: Read the discovered file to identify required markdown headers, description placeholders, issue citation rules, and checklists.
3. Populate Content: Replace placeholders with clear context summarizing the dependency rolls, configurations created, and rule blocks optimized. Check all applicable verification boxes ([x]).
4. Fallback: If no native template exists, construct a clean submission body containing a brief summary of modifications, relevant issue links, and static analysis/testing outcomes.

Output Command Structure

gh pr create \
  --title "Update dart_skills_lint dependency to <hash> and centralize config" \
  --body "<populated repository template content>"

Tips for the Flutter Repository (flutter/flutter)

When operating directly within the main Flutter codebase:

• Package Resolution: Run bin/flutter pub get at the repository root instead of dart pub get to prevent SDK version mismatch errors.
• Checksum Integrity: Updating dependencies natively breaks autogenerated pubspec checksum hashes. Always recalculate and update stale hashes by running bin/flutter update-packages --update-hashes.
• Test Orchestration: Run repository unit tests from the root context: bin/flutter test dev/tools/test/validate_skills_test.dart.
• Verification: Ensure zero static analysis warnings using dart analyze --fatal-infos and format all source code cleanly with dart format.