skills-lint-setup

Setting up Skill Validation with skills_lint

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

Steps

1. Add skills_lint as a dev_dependency.

   dev_dependencies:
     skills_lint: ^0.5.0
   

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.

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

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

   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.

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

   dart run skills_lint --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.

3. Wire it into CI. Use the GitHub Actions recipe from the README verbatim, or follow the pre-commit hook recipe below it.

When you're done

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