From 82505fd7ad88994e264b1e887a5d67c271a1cc6e Mon Sep 17 00:00:00 2001 From: Reid Baker Date: Fri, 10 Apr 2026 14:18:18 -0400 Subject: [PATCH 1/5] Add a skill in the location and format of https://pub.dev/packages/skills --- tool/dart_skills_lint/skills/README.md | 10 +++ .../dart-skills-lint-validation/SKILL.md | 65 +++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 tool/dart_skills_lint/skills/README.md create mode 100644 tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md diff --git a/tool/dart_skills_lint/skills/README.md b/tool/dart_skills_lint/skills/README.md new file mode 100644 index 00000000..fa983681 --- /dev/null +++ b/tool/dart_skills_lint/skills/README.md @@ -0,0 +1,10 @@ +# Skills shipped with dart_skills_lint + +The skills in this directory are shipped with the `dart_skills_lint` package. +They are intended for users of the package to help them use it effectively. + +To install these skills into your IDE, you can use the [skills](https://pub.dev/packages/skills) package on pub: +```bash +dart pub global activate skills +skills get +``` diff --git a/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md new file mode 100644 index 00000000..41d35ed1 --- /dev/null +++ b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md @@ -0,0 +1,65 @@ +--- +name: dart-skills-lint-validation +description: |- + Use this skill when you need to validate that AI agent skills meet the specification. + This includes generic validation of any skills for users that have Dart installed, + as well as integrating dart_skills_lint into a Dart project as a dev_dependency + to automate skill validation in tests or CI/CD. +--- + +# Skill Validation with dart_skills_lint + +## Usage for Agents (CLI) +Agents can use the `dart_skills_lint` CLI to validate skills. + +If the package is in your dependencies, run: +```bash +dart run dart_skills_lint -d .agents/skills +``` + +Or if activated globally: +```bash +dart pub global run dart_skills_lint -d .agents/skills +``` + +### Common Flags +- `-d`, `--skills-directory`: Specifies a root directory containing sub-folders of skills to validate. Can be passed multiple times. +- `-s`, `--skill`: Specifies an individual skill directory to validate directly. Can be passed multiple times. +- `-q`, `--quiet`: Hide non-error validation output. +- `-w`, `--print-warnings`: Enable printing of warning messages. + +## Setup for Dart Developers +To setup validation in your Dart project: + +1. Add `dart_skills_lint` to your `pubspec.yaml` as a `dev_dependency`: + ```yaml + dev_dependencies: + dart_skills_lint: ^0.2.0 + ``` + +2. You can also integrate the linter into your automated tests by importing the package and calling `validateSkills`. This has the advantage that your skills are automatically validated whenever you run `dart test`. + + Example `test/lint_skills_test.dart`: + ```dart + import 'package:dart_skills_lint/dart_skills_lint.dart'; + import 'package:test/test.dart'; + + void main() { + test('Run skills linter', () async { + await validateSkills( + skillDirPaths: ['.agents/skills'], + ); + }); + } + ``` + +3. (Optional) Create a configuration file `dart_skills_lint.yaml` in the root of your project to customize rules and directories for the CLI: +**Note:** If you use `validateSkills` directly in tests, the `dart_skills_lint.yaml` file is ignored by default, and you should pass configuration programmatically if needed. + ```yaml + dart_skills_lint: + rules: + check-relative-paths: error + check-absolute-paths: error + directories: + - path: ".agents/skills" + ``` From 71861b0735c5b7798f5a35c15192c93d73a61607 Mon Sep 17 00:00:00 2001 From: Reid Baker Date: Fri, 10 Apr 2026 15:13:22 -0400 Subject: [PATCH 2/5] Change example to ensure the validation is a success --- .../skills/dart-skills-lint-validation/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md index 41d35ed1..41eddc9c 100644 --- a/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md +++ b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md @@ -46,9 +46,10 @@ To setup validation in your Dart project: void main() { test('Run skills linter', () async { - await validateSkills( + final isValid = await validateSkills( skillDirPaths: ['.agents/skills'], ); + expect(isValid, isTrue); }); } ``` From 41725c742008896856e26f3b431a34f6b432bbd7 Mon Sep 17 00:00:00 2001 From: Reid Baker Date: Fri, 10 Apr 2026 15:15:14 -0400 Subject: [PATCH 3/5] fix the wrong version in the readme --- tool/dart_skills_lint/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tool/dart_skills_lint/README.md b/tool/dart_skills_lint/README.md index d55406d7..10c04138 100644 --- a/tool/dart_skills_lint/README.md +++ b/tool/dart_skills_lint/README.md @@ -30,7 +30,7 @@ Add `dart_skills_lint` to your Dart project or activate it globally. Add it to your `pubspec.yaml` (once published on pub.dev): ```yaml dev_dependencies: - dart_skills_lint: ^1.0.0 + dart_skills_lint: ^0.2.0 ``` Then run: ```bash From d500099c47185d9595e418da5e8de6bd9e1fe151 Mon Sep 17 00:00:00 2001 From: Reid Baker Date: Mon, 13 Apr 2026 11:20:51 -0400 Subject: [PATCH 4/5] use feedback after getting token to improve skill --- resources/flutter_skills.yaml | 20 +++- .../dart-skills-lint-validation/SKILL.md | 100 ++++++++++++++++-- 2 files changed, 113 insertions(+), 7 deletions(-) diff --git a/resources/flutter_skills.yaml b/resources/flutter_skills.yaml index 57140c95..5a226438 100644 --- a/resources/flutter_skills.yaml +++ b/resources/flutter_skills.yaml @@ -1441,4 +1441,22 @@ rendering Flutter widgets as images for display in the native widget UI. resources: - https://codelabs.developers.google.com/flutter-home-screen-widgets#0 - - https://pub.dev/packages/home_widget \ No newline at end of file + - https://pub.dev/packages/home_widget +- name: dart-skills-lint-validation + description: Validates that AI agent skills meet the specification using + dart_skills_lint. Use when checking skill directory structure, metadata, and + relative paths in a Dart project or globally. + instructions: | + Validating skills involves using the `dart_skills_lint` package to ensure + they meet the required specification. This process checks for the presence + of mandatory files, valid YAML frontmatter, and proper directory structure. + + To validate skills, you can run the linter via the CLI or integrate it into + automated tests. If the package is in your project dependencies, use `dart + run dart_skills_lint -d `. If activated globally, use + `dart pub global run dart_skills_lint -d `. You can also + import the package and call `validateSkills` in your Dart tests to automate + validation. Configuration can be customized using a `dart_skills_lint.yaml` + file or programmatically in tests. + resources: + - ../tool/dart_skills_lint/README.md \ No newline at end of file diff --git a/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md index 41eddc9c..cb027704 100644 --- a/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md +++ b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md @@ -7,17 +7,28 @@ description: |- to automate skill validation in tests or CI/CD. --- -# Skill Validation with dart_skills_lint +# Validating Skills with dart_skills_lint + +## Contents +- [Usage for Agents (CLI)](#usage-for-agents-cli) +- [Setup for Dart Developers](#setup-for-dart-developers) +- [Authoring Custom Rules](#authoring-custom-rules) +- [Workflow: Validating Skills](#workflow-validating-skills) +- [Specification Reference](#specification-reference) ## Usage for Agents (CLI) -Agents can use the `dart_skills_lint` CLI to validate skills. +Use the `dart_skills_lint` CLI to validate skills. Choose the appropriate workflow based on your environment: -If the package is in your dependencies, run: +### Scenario A: The package is in your project dependencies +Use this method if you are working within a project that has `dart_skills_lint` listed in `pubspec.yaml`. +Run: ```bash dart run dart_skills_lint -d .agents/skills ``` -Or if activated globally: +### Scenario B: The package is activated globally +Use this method if you want to validate skills across multiple projects without adding a dependency to each one. +Run: ```bash dart pub global run dart_skills_lint -d .agents/skills ``` @@ -27,9 +38,11 @@ dart pub global run dart_skills_lint -d .agents/skills - `-s`, `--skill`: Specifies an individual skill directory to validate directly. Can be passed multiple times. - `-q`, `--quiet`: Hide non-error validation output. - `-w`, `--print-warnings`: Enable printing of warning messages. +- `--fast-fail`: Halt execution immediately on the error. +- `--ignore-config`: Ignore the YAML configuration file entirely. ## Setup for Dart Developers -To setup validation in your Dart project: +Setup validation in your Dart project: 1. Add `dart_skills_lint` to your `pubspec.yaml` as a `dev_dependency`: ```yaml @@ -37,7 +50,7 @@ To setup validation in your Dart project: dart_skills_lint: ^0.2.0 ``` -2. You can also integrate the linter into your automated tests by importing the package and calling `validateSkills`. This has the advantage that your skills are automatically validated whenever you run `dart test`. +2. Integrate the linter into your automated tests by importing the package and calling `validateSkills`. This ensures your skills are automatically validated whenever you run `dart test`. Example `test/lint_skills_test.dart`: ```dart @@ -64,3 +77,78 @@ To setup validation in your Dart project: directories: - path: ".agents/skills" ``` + +## Authoring Custom Rules +To author custom rules, extend the `SkillRule` class and pass them to `validateSkills`. + +Example: +```dart +import 'package:dart_skills_lint/dart_skills_lint.dart'; + +class MyCustomRule extends SkillRule { + @override + final String name = 'my-custom-rule'; + + @override + final AnalysisSeverity severity = AnalysisSeverity.warning; + + @override + Future> validate(SkillContext context) async { + final errors = []; + 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; + } +} +``` + +Use it in your test: +```dart +await validateSkills( + skillDirPaths: ['.agents/skills'], + customRules: [MyCustomRule()], +); +``` + +## Workflow: Validating Skills +Follow this workflow to validate skills: + +1. **Run the validator**: Execute the linter on your skills directory. + ```bash + dart run dart_skills_lint -d .agents/skills + ``` +2. **Review errors**: Check the output for any errors or warnings. +3. **Fix violations**: Edit the `SKILL.md` or directory structure to resolve issues. +4. **Verify**: Re-run the validator to ensure all checks pass. + +### Task Progress +- [ ] Run validator +- [ ] Review errors +- [ ] Fix violations +- [ ] Verify clean run + +## Specification Reference +
+View Skill Specification Constraints + +### Directory and File Structure +- Mandatory `SKILL.md` file at the root of the skill folder. +- Directories starting with a dot `.` (e.g., `.dart_tool`) are ignored. + +### Metadata (YAML Frontmatter) +- Required fields: `name` and `description`. + +### Field Constraints +- **Name**: Max 64 characters, lowercase alphanumeric and hyphens only. Must match the parent directory name. +- **Description**: Max 1024 characters. +- **Compatibility**: Max 500 characters. +
From 9263bb8ec3a50a7506ceeb487aaad4f257363a52 Mon Sep 17 00:00:00 2001 From: Reid Baker Date: Tue, 14 Apr 2026 17:18:34 -0400 Subject: [PATCH 5/5] Revert yaml for custom skills integration --- resources/flutter_skills.yaml | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/resources/flutter_skills.yaml b/resources/flutter_skills.yaml index 5a226438..57140c95 100644 --- a/resources/flutter_skills.yaml +++ b/resources/flutter_skills.yaml @@ -1441,22 +1441,4 @@ rendering Flutter widgets as images for display in the native widget UI. resources: - https://codelabs.developers.google.com/flutter-home-screen-widgets#0 - - https://pub.dev/packages/home_widget -- name: dart-skills-lint-validation - description: Validates that AI agent skills meet the specification using - dart_skills_lint. Use when checking skill directory structure, metadata, and - relative paths in a Dart project or globally. - instructions: | - Validating skills involves using the `dart_skills_lint` package to ensure - they meet the required specification. This process checks for the presence - of mandatory files, valid YAML frontmatter, and proper directory structure. - - To validate skills, you can run the linter via the CLI or integrate it into - automated tests. If the package is in your project dependencies, use `dart - run dart_skills_lint -d `. If activated globally, use - `dart pub global run dart_skills_lint -d `. You can also - import the package and call `validateSkills` in your Dart tests to automate - validation. Configuration can be customized using a `dart_skills_lint.yaml` - file or programmatically in tests. - resources: - - ../tool/dart_skills_lint/README.md \ No newline at end of file + - https://pub.dev/packages/home_widget \ No newline at end of file