diff --git a/tool/dart_skills_lint/README.md b/tool/dart_skills_lint/README.md index d55406d..10c0413 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 diff --git a/tool/dart_skills_lint/skills/README.md b/tool/dart_skills_lint/skills/README.md new file mode 100644 index 0000000..fa98368 --- /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 0000000..cb02770 --- /dev/null +++ b/tool/dart_skills_lint/skills/dart-skills-lint-validation/SKILL.md @@ -0,0 +1,154 @@ +--- +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. +--- + +# 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) +Use the `dart_skills_lint` CLI to validate skills. Choose the appropriate workflow based on your environment: + +### 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 +``` + +### 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 +``` + +### 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. +- `--fast-fail`: Halt execution immediately on the error. +- `--ignore-config`: Ignore the YAML configuration file entirely. + +## Setup for Dart Developers +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. 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 + import 'package:dart_skills_lint/dart_skills_lint.dart'; + import 'package:test/test.dart'; + + void main() { + test('Run skills linter', () async { + final isValid = await validateSkills( + skillDirPaths: ['.agents/skills'], + ); + expect(isValid, isTrue); + }); + } + ``` + +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" + ``` + +## 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. +