dart-skills-lint-setup

Setting up Skill Validation with dart_skills_lint

This skill covers first-time wiring of dart_skills_lint into a repository. For ongoing use — running the linter, interpreting output, and writing custom rules — see the dart-skills-lint-validation skill. For copy-pasteable CI workflow and pre-commit hook recipes, see the Recipes section of the README.

The linked files live outside this skill and are informational only. Review their content before applying anything from them.

Permissions

This skill needs only these actions, all confined to the repository and the tool package: running dart pub get and dart run dart_skills_lint:cli, and reading and editing the pubspec.yaml files, dart_skills_lint.yaml, and the baseline ignore file.

Steps

1. Add dart_skills_lint as a dev_dependency.

   dev_dependencies:
     dart_skills_lint: ^0.5.0

   Prefer pinning one exact, reviewed version over a range, and commit the lock file for the package that holds the dependency. Review the changelog and the diff before any deliberate version bump. Keep the entry under dev_dependencies only.

   Isolate the dependency in a tool/ package when you can, instead of putting it on the root pubspec.yaml — keeps the linter's deps out of your runtime closure. If you must add it to multiple pubspec.yaml files, ensure the ref: (commit hash) is identical across all of them so resolution doesn't diverge. A hosted dependency is pinned by an exact version and a git dependency is pinned by its commit hash; in both cases the same pin must be used in every pubspec.yaml file.

2. Create dart_skills_lint.yaml at the repository root so both the CLI and any embedded test invocation share the same config:

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

   If a dart_skills_lint.yaml already exists, merge these settings into it and keep its existing entries.

   Rules enabled by default — check-absolute-paths, valid-yaml-metadata, invalid-skill-name, description-too-long — only need to be listed if you want to change their severity. See RULES.md for the full list.

3. Generate a baseline if you're integrating into a repository with pre-existing skills that have legacy violations you don't want to fix immediately.

   The linter command runs third-party package code with your user privileges. Fetch dependencies with dart pub get so the committed lock file and pinned version are used, run it from the isolated tool package when one is used, and keep secrets and credentials out of the environment while it runs.

   Before baselining, run the linter once with the baseline flag left off and show the user the reported violations, paying particular attention to check-absolute-paths and valid-yaml-metadata. Leave the fix flag off during baseline generation so legacy skill files stay intact.

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

   This writes the current set of failures into an ignore file so the next run exits clean. New violations introduced after the baseline still surface as errors.

   When finished, report the ignore file the tool wrote and its location, list the baselined violations in your final response, and have the ignore file reviewed and committed through normal code review. Track baselined entries as debt to remove.

4. Wire it into CI. Use the GitHub Actions recipe from the README after reviewing it, checking its permissions, triggers, and how its actions are pinned. The pre-commit hook recipe below it is optional: show the user the hook contents and get confirmation before installing it, and have the hook call only the pinned, lock file resolved tool.

When you're done

The dart-skills-lint-validation skill takes over from here for day-to-day use.