sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/tool/generator/lib/src/services/skill_instructions.dart

@@ -0,0 +1,30 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Instructions for authoring Skills.
+const String skillInstructions = '''
+# Role
+Act as an Expert Skill Author. Generate high-performance, well-structured Skill modules (SKILL.md) that follow the "Skill authoring best practices" guide.
+
+# Authoring Guidelines
+1. **Concise & Expert:** Assume the AI is highly competent. Only provide context the AI doesn't already have. Challenge each paragraph: "Does this justify its token cost?". Avoid explaining basic concepts.
+2. **Imperative Mood:** Write all instructions and best practices using the imperative mood (e.g., "Implement the repository..." rather than "The agent should implement...").
+3. **Single File Constraint:** Do not use external file references (e.g., [other.md](other.md)). Include all necessary content within the SKILL.md file. Use <details> tags to collapse lengthy reference material if it exceeds 500 lines.
+4. **Naming:** Use the gerund form (verb + -ing) for the H1 title.
+5. **Workflows & Feedback Loops:** For complex tasks, implement sequential workflows with "Task Progress" checklists that the agent can copy to track progress. Include feedback loops where the agent must "Run validator -> review errors -> fix" for quality-critical operations.
+6. **Conditional Logic:** Use conditional workflows to guide the agent through decision points (e.g., "If creating NEW content..." vs "If EDITING existing content...").
+7. **Examples:** When output quality depends on style or specific formatting, provide clear input/output pairs or high-fidelity implementation examples.
+8. **Consistent Terminology:** Choose one clear term for concepts (e.g., "API endpoint", "Widget state") and use it throughout.
+9. **Single File Constraint:** Do not use external file references (e.g., [other.md](other.md)). Include all necessary content within the SKILL.md file. Use <details> tags to collapse lengthy reference material if it exceeds 500 lines.
+
+# Formatting Rules
+1. **No YAML**: DO NOT include any YAML frontmatter in your response. Start immediately with the markdown content (e.g., the H1 title).
+2. **Raw Markdown**: DO NOT wrap the entire output in a markdown code block (e.g., ```markdown ... ```). Return raw markdown text.
+3. **Structure**: When generating or updating a skill module, follow this hierarchy:
+   - **# [Gerund Form Title]**
+   - **## Contents**: A table of contents linking to all H2 sections.
+   - **## [Domain/Topic Sections]**: Organized H2 sections covering concepts and core guidelines.
+   - **## [Workflow Sections]**: Sequential, checklist-based guides for common tasks.
+   - **## Examples** (If applicable): Concrete examples demonstrating the preferred implementation.
+''';

package/skills/flutter-skills/tool/generator/pubspec.yaml

@@ -0,0 +1,32 @@
+name: skills
+description: A command-line application for creating and validating Agent Skills.
+version: 0.0.1
+resolution: workspace
+
+environment:
+  sdk: ^3.10.8
+
+# Add regular dependencies here.
+dependencies:
+  args: ^2.7.0
+  file: ^7.0.1
+  glob: ^2.1.3
+  google_cloud_ai_generativelanguage_v1beta: ^0.5.2
+  googleapis_auth: ^2.0.0
+  html: ^0.15.6
+  http: ^1.6.0
+  logging: ^1.3.0
+  meta: ^1.18.1
+  path: ^1.9.1
+  platform: ^3.1.6
+  retry: ^3.1.2
+  yaml: ^3.1.2
+
+dev_dependencies:
+  build_verify: ^3.1.0
+  coverage: ^1.15.0
+  dart_skills_lint:
+    path: ../dart_skills_lint
+  lints: ^6.0.0
+  test: ^1.25.6
+

package/skills/flutter-skills/tool/generator/test/commands/base_skill_command_test.dart

@@ -0,0 +1,131 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:args/command_runner.dart';
+import 'package:http/testing.dart';
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+import 'package:skills/src/commands/base_skill_command.dart';
+import 'package:skills/src/models/skill_params.dart';
+import 'package:skills/src/services/gemini_service.dart';
+import 'package:test/test.dart';
+
+class _TestSkillCommand extends BaseSkillCommand {
+  _TestSkillCommand({required super.httpClient, super.environment})
+    : super(logger: Logger('_TestSkillCommand'));
+
+  @override
+  String get name => 'test-command';
+
+  @override
+  String get description => 'Description';
+
+  @override
+  Future<void> runSkill(
+    SkillParams skill,
+    GeminiService gemini,
+    Directory outputDir,
+    int thinkingBudget, {
+    Directory? configDir,
+  }) async {}
+}
+
+void main() {
+  group('BaseSkillCommand Edge Cases', () {
+    late CommandRunner<void> runner;
+    late Directory tempDir;
+    late MockClient mockClient;
+    final logs = <String>[];
+
+    setUp(() async {
+      tempDir = await Directory.systemTemp.createTemp(
+        'base_skill_commands_test',
+      );
+      mockClient = MockClient((request) async => throw UnimplementedError());
+      runner = CommandRunner<void>('skills', 'Test runner')
+        ..addCommand(_TestSkillCommand(httpClient: mockClient));
+
+      Logger.root.level = Level.INFO;
+      Logger.root.onRecord.listen((record) => logs.add(record.message));
+      logs.clear();
+    });
+
+    tearDown(() async {
+      await tempDir.delete(recursive: true);
+      logs.clear();
+    });
+
+    test('logs severe error when configuration file not found', () async {
+      final path = p.join(tempDir.path, 'missing.yaml');
+      await IOOverrides.runZoned(() async {
+        await runner.run(['test-command', path]);
+      }, getCurrentDirectory: () => tempDir);
+
+      expect(logs, contains('Configuration file not found: $path'));
+    });
+
+    test('logs warning when no skills match the --skill filter', () async {
+      final configFile = File(p.join(tempDir.path, 'config.yaml'));
+      await configFile.writeAsString(
+        jsonEncode(<Map<String, dynamic>>[
+          {
+            'name': 'existent-skill',
+            'description': 'desc',
+            'resources': <String>[],
+          },
+        ]),
+      );
+
+      await IOOverrides.runZoned(() async {
+        await runner.run([
+          'test-command',
+          configFile.path,
+          '--skill',
+          'non-existent',
+        ]);
+      }, getCurrentDirectory: () => tempDir);
+
+      expect(logs, contains('No skill found with name: non-existent'));
+    });
+
+    test('logs warning when configuration file contains no skills', () async {
+      final configFile = File(p.join(tempDir.path, 'empty.yaml'));
+      await configFile.writeAsString('[]');
+
+      await IOOverrides.runZoned(() async {
+        await runner.run(['test-command', configFile.path]);
+      }, getCurrentDirectory: () => tempDir);
+
+      expect(logs, contains('No skills found in configuration file.'));
+    });
+
+    test('logs severe error when GEMINI_API_KEY is not set', () async {
+      final configFile = File(p.join(tempDir.path, 'config.yaml'));
+      await configFile.writeAsString(
+        jsonEncode(<Map<String, dynamic>>[
+          {
+            'name': 'existent-skill',
+            'description': 'desc',
+            'resources': <String>[],
+          },
+        ]),
+      );
+
+      // Override environment parameter to simulate missing api key
+      runner = CommandRunner(
+        'skills',
+        'Test runner',
+      )..addCommand(_TestSkillCommand(httpClient: mockClient, environment: {}));
+
+      await IOOverrides.runZoned(() async {
+        await runner.run(['test-command', configFile.path]);
+      }, getCurrentDirectory: () => tempDir);
+
+      expect(logs, contains('GEMINI_API_KEY environment variable not set.'));
+    });
+  });
+}

package/skills/flutter-skills/tool/generator/test/commands/validate_skills_input_test.dart

@@ -0,0 +1,263 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:args/command_runner.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+import 'package:skills/src/commands/validate_skill_command.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('ValidateSkillCommand Input Validation', () {
+    late CommandRunner<void> runner;
+    late Directory tempDir;
+    late MockClient mockClient;
+    final logs = <String>[];
+
+    setUp(() async {
+      tempDir = await Directory.systemTemp.createTemp(
+        'validate_skills_input_test',
+      );
+      mockClient = MockClient((request) async => http.Response('', 200));
+
+      Logger.root.level = Level.INFO;
+      Logger.root.onRecord.listen((record) {
+        logs.add(record.message);
+      });
+      logs.clear();
+    });
+
+    tearDown(() async {
+      await tempDir.delete(recursive: true);
+      logs.clear();
+    });
+
+    Future<void> runValidation(String filename, String content) async {
+      final configFile = File(p.join(tempDir.path, filename));
+      await configFile.writeAsString(content);
+
+      runner = CommandRunner<void>('skills', 'Test runner')
+        ..addCommand(
+          ValidateSkillCommand(
+            environment: {'GEMINI_API_KEY': 'test-key'},
+            outputDir: tempDir,
+            httpClient: mockClient,
+          ),
+        );
+
+      await IOOverrides.runZoned(() async {
+        await runner.run(['validate-skill', configFile.path]);
+      }, getCurrentDirectory: () => tempDir);
+    }
+
+    test('passes when configuration is perfectly valid', () async {
+      final content = jsonEncode([
+        {
+          'name': 'flutter-test-skill',
+          'description': 'A Flutter test skill',
+          'resources': ['https://example.com/doc'],
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(logs, isNot(contains('Configuration validation failed.')));
+    });
+
+    test('fails when root structure is not a list', () async {
+      final content = jsonEncode({'name': 'flutter-test-skill'});
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(
+        logs,
+        contains('Invalid configuration: Root must be a YAML list.'),
+      );
+    });
+
+    test('fails when configuration list is empty', () async {
+      final content = jsonEncode([]);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(logs, contains('Configuration list must not be empty.'));
+    });
+
+    test('fails when item is not a map', () async {
+      final content = jsonEncode(['just-a-string-not-a-map']);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(logs, contains('Item 0 is not a Map.'));
+      expect(logs, contains('Configuration validation failed.'));
+    });
+
+    test('fails when fields are missing', () async {
+      final content = jsonEncode([
+        {'name': 'flutter-skill'},
+      ]);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(
+        logs,
+        contains(
+          'Skill "flutter-skill" is missing required field "description".',
+        ),
+      );
+      expect(
+        logs,
+        contains(
+          'Skill "flutter-skill" is missing required field "resources".',
+        ),
+      );
+      expect(logs, contains('Configuration validation failed.'));
+    });
+
+    test('fails when skill name is not kabob-case', () async {
+      final content = jsonEncode([
+        {
+          'name': 'flutter_skill_invalid',
+          'description': 'A Flutter skill description',
+          'resources': ['https://example.com'],
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(
+        logs,
+        contains(
+          'Skill name "flutter_skill_invalid" must be kabob-case (e.g. abc-def).',
+        ),
+      );
+      expect(logs, contains('Configuration validation failed.'));
+    });
+
+    test(
+      'fails when flutter_skills.yaml name or description conventions are violated',
+      () async {
+        final content = jsonEncode([
+          {
+            'name': 'dart-skill',
+            'description': 'A skill description with no framework keyword',
+            'resources': ['https://example.com'],
+          },
+        ]);
+
+        await runValidation('flutter_skills.yaml', content);
+        expect(
+          logs,
+          contains(
+            'Skill name "dart-skill" in flutter_skills.yaml must start with "flutter-".',
+          ),
+        );
+        expect(logs, contains('Configuration validation failed.'));
+      },
+    );
+
+    test(
+      'fails when dart_skills.yaml name or description conventions are violated',
+      () async {
+        final content = jsonEncode([
+          {
+            'name': 'flutter-skill',
+            'description': 'A skill description with no language keyword',
+            'resources': ['https://example.com'],
+          },
+        ]);
+
+        await runValidation('dart_skills.yaml', content);
+        expect(
+          logs,
+          contains(
+            'Skill name "flutter-skill" in dart_skills.yaml must start with "dart-".',
+          ),
+        );
+        expect(logs, contains('Configuration validation failed.'));
+      },
+    );
+
+    test('fails when resources list is empty', () async {
+      final content = jsonEncode([
+        {
+          'name': 'flutter-skill',
+          'description': 'A Flutter skill description',
+          'resources': <dynamic>[],
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(
+        logs,
+        contains('Skill "flutter-skill" field "resources" must not be empty.'),
+      );
+      expect(logs, contains('Configuration validation failed.'));
+    });
+
+    test('fails when resource URL uses insecure HTTP protocol', () async {
+      final content = jsonEncode([
+        {
+          'name': 'flutter-skill',
+          'description': 'A Flutter skill description',
+          'resources': ['http://example.com/insecure'],
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content);
+      expect(
+        logs,
+        contains(
+          'Skill "flutter-skill" resource URL "http://example.com/insecure" must use secure HTTPS.',
+        ),
+      );
+      expect(logs, contains('Configuration validation failed.'));
+    });
+
+    test('fails when fields have invalid types', () async {
+      final content1 = jsonEncode([
+        {
+          'name': 12345, // int, should be string
+          'description': 'A Flutter skill description',
+          'resources': ['https://example.com'],
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content1);
+      expect(logs, contains('Item 0 field "name" must be a string.'));
+
+      logs.clear();
+      final content2 = jsonEncode([
+        {
+          'name': 'flutter-skill',
+          'description': true, // bool, should be string
+          'resources': ['https://example.com'],
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content2);
+      expect(
+        logs,
+        contains('Skill "flutter-skill" field "description" must be a string.'),
+      );
+
+      logs.clear();
+      final content3 = jsonEncode([
+        {
+          'name': 'flutter-skill',
+          'description': 'A Flutter skill description',
+          'resources': ['https://example.com'],
+          'instructions': 999, // int, should be string
+        },
+      ]);
+
+      await runValidation('flutter_skills.yaml', content3);
+      expect(
+        logs,
+        contains(
+          'Skill "flutter-skill" field "instructions" must be a string.',
+        ),
+      );
+    });
+  });
+}

package/skills/flutter-skills/tool/generator/test/custom_skill_rules/last_modified_rule.dart

@@ -0,0 +1,32 @@
+import 'package:dart_skills_lint/dart_skills_lint.dart';
+
+class LastModifiedRule extends SkillRule {
+  static const _metadataKey = 'metadata';
+  static const _lastModifiedKey = 'last_modified';
+
+  @override
+  final String name = 'generator:last-modified';
+
+  @override
+  final AnalysisSeverity severity = AnalysisSeverity.error;
+
+  @override
+  Future<List<ValidationError>> validate(SkillContext context) async {
+    final errors = <ValidationError>[];
+    final yaml = context.parsedYaml;
+    if (yaml == null) return errors;
+
+    final Object? metadata = yaml[_metadataKey];
+    if (metadata is! Map || !metadata.containsKey(_lastModifiedKey)) {
+      errors.add(
+        ValidationError(
+          ruleId: name,
+          severity: severity,
+          file: 'SKILL.md',
+          message: 'Missing field: $_metadataKey.$_lastModifiedKey',
+        ),
+      );
+    }
+    return errors;
+  }
+}

package/skills/flutter-skills/tool/generator/test/generate_skills_retry_test.dart

@@ -0,0 +1,105 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:args/command_runner.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+import 'package:skills/src/commands/generate_skill_command.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('GenerateSkillsCommand Retry Logic', () {
+    late CommandRunner<void> runner;
+    late Directory tempDir;
+    late File inputFile;
+
+    setUp(() async {
+      tempDir = await Directory.systemTemp.createTemp('skills_retry_test');
+      inputFile = File(p.join(tempDir.path, 'input.yaml'));
+      runner = CommandRunner<void>('skills', 'Test runner');
+    });
+
+    tearDown(() async {
+      await tempDir.delete(recursive: true);
+    });
+
+    test('retries failed LLM calls up to 3 times', () async {
+      const url = 'https://example.com/retry';
+      inputFile.writeAsStringSync(
+        jsonEncode([
+          {
+            'name': 'retry_skill',
+            'description': 'Retry Description',
+            'resources': [url],
+          },
+        ]),
+      );
+
+      var attemptCount = 0;
+      final logs = <String>[];
+      final sub = Logger.root.onRecord.listen((record) {
+        logs.add(record.message);
+      });
+      addTearDown(sub.cancel);
+
+      final mockClient = MockClient((request) async {
+        if (request.url.toString() == url) {
+          return http.Response('<html>Content</html>', 200);
+        }
+
+        if (request.url.toString().contains('generativelanguage')) {
+          attemptCount++;
+          if (attemptCount < 3) {
+            throw Exception('Simulated Network Error');
+          }
+          return http.Response(
+            jsonEncode({
+              'candidates': [
+                {
+                  'content': {
+                    'parts': [
+                      {'text': '---\nname: skill\n---\nContent'},
+                    ],
+                  },
+                },
+              ],
+            }),
+            200,
+          );
+        }
+        return http.Response('Not Found', 404);
+      });
+
+      final command = GenerateSkillCommand(
+        environment: {'GEMINI_API_KEY': 'test-key'},
+        httpClient: mockClient,
+        outputDir: tempDir,
+      );
+      runner.addCommand(command);
+
+      await runner.run(['generate-skill', inputFile.path]);
+
+      expect(
+        attemptCount,
+        3,
+        reason: 'Should attempt 3 times (1 initial + 2 retries)',
+      );
+      expect(
+        logs,
+        contains(contains('Retrying Gemini generation')),
+        reason: 'Should log retry warnings',
+      );
+      expect(
+        logs,
+        contains(contains('Generated')),
+        reason: 'Should eventually succeed',
+      );
+    });
+  });
+}