sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/tool/generator/README.md

@@ -0,0 +1,150 @@
+# Skills CLI
+
+The Skills CLI simplifies the process of creating "Agent Skills" from external documentation. It allows you to crawl documentation websites to discover relevant pages and then uses Generative AI (Gemini) to convert those pages into structured `SKILL.md` files that agents can use.
+
+## Context
+
+*   [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+## Prerequisite
+
+This tool requires the `GEMINI_API_KEY` environment variable to be set.
+
+## Commands
+
+> [!NOTE]
+> To use the default configuration file path (`resources/flutter_skills.yaml`), commands should be run from the root of the repository as: `dart run tool/generator/bin/skills.dart <command>`.
+> Alternatively, if running from this directory, specify the path to the configuration file explicitly (e.g., `../../resources/flutter_skills.yaml`).
+
+### `generate-skill`
+
+Generates `SKILL.md` files from a YAML configuration file. Use the `--skill` option to generate a specific skill.
+
+**Usage:**
+```bash
+dart run skills generate-skill [options] [config_file]
+```
+
+**Arguments:**
+*   `[config_file]`: Path to the YAML configuration file. Defaults to `resources/flutter_skills.yaml`.
+
+**Options:**
+*   `--skill`: Filter to generate only the specified skill by name.
+*   `--directory` (`-d`): The directory to output the generated skill folder. Defaults to `../skills/`.
+*   `--dry-run`: Performs a dry run, showing what would be generated and token count without writing files.
+
+**Example:**
+Generate all skills defined in resources/flutter_skills.yaml to the skills/ directory:
+
+```bash
+dart run skills generate-skill
+```
+
+Generate only the 'flutter-layout' skill to a custom directory:
+
+```bash
+dart run skills generate-skill --skill flutter-layout --directory ../skills
+```
+
+### `update-skill`
+
+Updates an existing skill by combining its current content with fetched resources and new instructions.
+
+**Usage:**
+```bash
+dart run skills update-skill [options] [config_file]
+```
+
+**Arguments:**
+*   `[config_file]`: Path to the YAML configuration file. Defaults to `resources/flutter_skills.yaml`.
+
+**Options:**
+*   `--skill`: Filter to update only the specified skill by name.
+*   `--directory` (`-d`): The directory to search for skills. Defaults to `../skills/`.
+*   `--thinking-budget`: The token budget for the model to "think" before generating content. Defaults to 2048.
+
+**Example:**
+Update all skills defined in resources/flutter_skills.yaml:
+
+```bash
+dart run skills update-skill
+```
+
+Update only the 'flutter-layout' skill:
+
+```bash
+dart run skills update-skill --skill flutter-layout
+```
+
+### `validate-skill`
+
+Validates skills by re-generating and comparing with existing skills. This is useful for testing prompts or verifying consistency.
+
+**Usage:**
+```bash
+dart run skills validate-skill [options] [config_file]
+```
+
+**Arguments:**
+*   `[config_file]`: Path to the YAML configuration file. Defaults to `resources/flutter_skills.yaml`.
+
+**Options:**
+*   `--skill`: Validate only the specified skill by name.
+*   `--directory` (`-d`): The directory containing the generated skills to validate. Defaults to `../skills/`.
+*   `--thinking-budget`: The token budget for the model to "think" before generating content. Defaults to 2048.
+
+**Example:**
+Validate skills in the default 'skills' directory:
+
+```bash
+dart run skills validate-skill
+```
+
+Validate skills in a custom directory:
+
+```bash
+dart run skills validate-skill --directory ../validation_results
+```
+
+### `update-readme`
+
+Updates the `README.md` file with a table of available skills.
+
+**Usage:**
+```bash
+dart run skills update-readme [config_file] [readme_file]
+```
+
+**Arguments:**
+*   `[config_file]`: Path to the YAML configuration file. Defaults to `resources/flutter_skills.yaml`.
+*   `[readme_file]`: Path to the README.md file to update. Defaults to `../README.md`.
+
+**Example:**
+Update the root README.md:
+
+```bash
+dart run skills update-readme
+```
+
+## Configuration
+
+The default configuration file is located at `resources/flutter_skills.yaml`. It contains a list of skill definitions:
+
+```yaml
+- name: flutter-layout
+  description: "..."
+  resources:
+    - https://docs.flutter.dev/ui/widgets/layout
+    - https://docs.flutter.dev/ui/layout
+    - ../packages/flutter/lib/src/widgets/layout.md
+```
+
+## Development
+
+To run analysis, formatting, and tests, navigate to this directory (`tool/generator`) and run:
+
+```bash
+dart analyze
+dart format .
+dart test
+```

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

@@ -0,0 +1,143 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+linter:
+  # The lint rules applied to this project can be customized in the
+  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
+  # included above or to enable additional rules. A list of all available lints
+  # and their documentation is published at https://dart.dev/lints.
+  #
+  # Instead of disabling a lint rule for the entire project in the
+  # section below, it can also be suppressed for a single line of code
+  # or a specific dart file by using the `// ignore: name_of_lint` and
+  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
+  # producing the lint.
+  rules:
+    # Error Prevention
+    unnecessary_statements: true
+    no_self_assignments: true
+    avoid_catches_without_on_clauses: true
+    avoid_catching_errors: true
+    avoid_returning_this: true
+    avoid_void_async: true
+    await_only_futures: true
+    cancel_subscriptions: true
+    close_sinks: true
+    discarded_futures: true
+    literal_only_boolean_expressions: true
+    no_adjacent_strings_in_list: true
+    no_logic_in_create_state: true
+    only_throw_errors: true
+    prefer_is_empty: true
+    prefer_is_not_empty: true
+    test_types_in_equals: true
+    throw_in_finally: true
+    unawaited_futures: true
+    unnecessary_null_aware_assignments: true
+    unnecessary_null_in_if_null_operators: true
+    unnecessary_nullable_for_final_variable_declarations: true
+    use_build_context_synchronously: true
+    use_rethrow_when_possible: true
+
+    # Style & Formatting
+    always_declare_return_types: true
+    always_put_required_named_parameters_first: true
+    avoid_escaping_inner_quotes: true
+    avoid_function_literals_in_foreach_calls: true
+    avoid_init_to_null: true
+    avoid_multiple_declarations_per_line: true
+    avoid_positional_boolean_parameters: true
+    avoid_private_typedef_functions: true
+    avoid_redundant_argument_values: true
+    avoid_renaming_method_parameters: true
+    avoid_shadowing_type_parameters: true
+    avoid_types_on_closure_parameters: true
+    avoid_unused_constructor_parameters: true
+    camel_case_extensions: true
+    cascade_invocations: true
+    curly_braces_in_flow_control_structures: true
+    directives_ordering: true
+    eol_at_end_of_file: true
+    file_names: true
+    library_names: true
+    no_leading_underscores_for_library_prefixes: true
+    no_leading_underscores_for_local_identifiers: true
+    omit_local_variable_types: true
+    prefer_const_constructors: true
+    prefer_const_constructors_in_immutables: true
+    prefer_const_declarations: true
+    prefer_const_literals_to_create_immutables: true
+    prefer_final_fields: true
+    prefer_final_in_for_each: true
+    prefer_final_locals: true
+    prefer_if_elements_to_conditional_expressions: true
+    prefer_interpolation_to_compose_strings: true
+    prefer_mixin: true
+    prefer_relative_imports: true
+    prefer_single_quotes: true
+    require_trailing_commas: true
+    sized_box_for_whitespace: true
+    sort_child_properties_last: true
+    sort_constructors_first: true
+    sort_unnamed_constructors_first: true
+    type_init_formals: true
+    unnecessary_await_in_return: true
+    unnecessary_breaks: true
+    unnecessary_const: true
+    unnecessary_constructor_name: true
+    unnecessary_lambdas: true
+    unnecessary_late: true
+    unnecessary_new: true
+    unnecessary_parenthesis: true
+    unnecessary_raw_strings: true
+    unnecessary_string_escapes: true
+    unnecessary_string_interpolations: true
+    unnecessary_this: true
+    use_function_type_syntax_for_parameters: true
+    use_if_null_to_convert_nulls_to_bools: true
+    use_string_buffers: true
+    use_to_and_as_if_applicable: true
+
+    # Best Practices
+    annotate_redeclares: true
+    avoid_annotating_with_dynamic: true
+    avoid_bool_literals_in_conditional_expressions: true
+    avoid_classes_with_only_static_members: true
+    avoid_print: true
+    avoid_setters_without_getters: true
+    depend_on_referenced_packages: true
+    deprecated_consistency: true
+    library_private_types_in_public_api: true
+    prefer_asserts_in_initializer_lists: true
+    prefer_constructors_over_static_methods: true
+    secure_pubspec_urls: true
+    sort_pub_dependencies: true
+    unnecessary_to_list_in_spreads: true
+    use_super_parameters: true
+    annotate_overrides: true
+
+    # Documentation
+    dangling_library_doc_comments: true
+    library_annotations: true
+    public_member_api_docs: true
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options

package/skills/flutter-skills/tool/generator/bin/skills.dart

@@ -0,0 +1,73 @@
+// 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:io';
+
+import 'package:args/command_runner.dart';
+import 'package:http/http.dart' as http;
+import 'package:logging/logging.dart';
+import 'package:skills/src/commands/generate_skill_command.dart';
+import 'package:skills/src/commands/update_readme_command.dart';
+import 'package:skills/src/commands/update_skill_command.dart';
+import 'package:skills/src/commands/validate_skill_command.dart';
+
+const String version = '0.1.0';
+
+void main(List<String> arguments) async {
+  final httpClient = http.Client();
+
+  final runner =
+      CommandRunner<void>('skills', 'A sample command-line application.')
+        ..addCommand(GenerateSkillCommand(httpClient: httpClient))
+        ..addCommand(UpdateSkillCommand(httpClient: httpClient))
+        ..addCommand(ValidateSkillCommand(httpClient: httpClient))
+        ..addCommand(UpdateReadmeCommand());
+
+  runner.argParser.addFlag(
+    'version',
+    negatable: false,
+    help: 'Print the tool version.',
+  );
+  runner.argParser.addFlag(
+    'verbose',
+    abbr: 'v',
+    negatable: false,
+    help: 'Show additional command output.',
+  );
+
+  try {
+    final results = runner.parse(arguments);
+    if (results.flag('version')) {
+      stdout.writeln('skills version: $version');
+      return;
+    }
+
+    _configureLogging(results.flag('verbose'));
+
+    if (results.flag('verbose')) {
+      Logger.root.fine('All arguments: ${results.arguments}');
+    }
+
+    await runner.run(arguments);
+  } on UsageException catch (e) {
+    stderr.writeln(e);
+    exit(64);
+  } on Exception catch (e) {
+    stderr.writeln('An error occurred: $e');
+    exit(1);
+  } finally {
+    httpClient.close();
+  }
+}
+
+void _configureLogging(bool verbose) {
+  Logger.root.level = verbose ? Level.ALL : Level.INFO;
+  Logger.root.onRecord.listen((record) {
+    if (record.level >= Level.SEVERE) {
+      stderr.writeln(record.message);
+    } else {
+      stdout.writeln(record.message);
+    }
+  });
+}

package/skills/flutter-skills/tool/generator/lib/src/commands/base_skill_command.dart

@@ -0,0 +1,87 @@
+// 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:io';
+
+import 'package:http/http.dart' as http;
+
+import '../models/skill_params.dart';
+import '../services/gemini_service.dart';
+import 'base_yaml_command.dart';
+
+/// Base command for skill operations requiring AI generation.
+abstract class BaseSkillCommand extends BaseYamlCommand {
+  /// Creates a new [BaseSkillCommand].
+  BaseSkillCommand({
+    required this.httpClient,
+    required super.logger,
+    super.outputDir,
+    this.environment,
+  }) {
+    argParser
+      ..addOption(
+        'thinking-budget',
+        help:
+            'The token budget for the model to "think". Defaults to ${GeminiService.defaultThinkingBudget} (recommended for technical documentation).',
+        defaultsTo: GeminiService.defaultThinkingBudget.toString(),
+      )
+      ..addFlag(
+        'dry-run',
+        abbr: 'n',
+        help:
+            'Simulate the command without making API calls or modifying files.',
+        negatable: false,
+      );
+  }
+
+  /// The HTTP client used for fetching resources.
+  final http.Client httpClient;
+
+  /// Optional override for the environment variables, for testing.
+  final Map<String, String>? environment;
+
+  @override
+  Future<void> runWithSkills(
+    List<SkillParams> skills,
+    Directory outputDir, {
+    Directory? configDir,
+  }) async {
+    final apiKey = (environment ?? Platform.environment)['GEMINI_API_KEY'];
+    if (apiKey == null) {
+      logger.severe('GEMINI_API_KEY environment variable not set.');
+      return;
+    }
+
+    final gemini = GeminiService(apiKey: apiKey, httpClient: httpClient);
+
+    int thinkingBudget;
+    try {
+      thinkingBudget = int.parse(argResults!['thinking-budget'] as String);
+    } on FormatException {
+      logger.warning(
+        'Invalid thinking-budget: ${argResults!['thinking-budget']}. Skipping.',
+      );
+      return;
+    }
+
+    for (final skill in skills) {
+      await runSkill(
+        skill,
+        gemini,
+        outputDir,
+        thinkingBudget,
+        configDir: configDir,
+      );
+    }
+  }
+
+  /// Executes the command for a specific skill.
+  Future<void> runSkill(
+    SkillParams skill,
+    GeminiService gemini,
+    Directory outputDir,
+    int thinkingBudget, {
+    Directory? configDir,
+  });
+}

package/skills/flutter-skills/tool/generator/lib/src/commands/base_yaml_command.dart

@@ -0,0 +1,83 @@
+// 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:logging/logging.dart';
+import 'package:yaml/yaml.dart';
+
+import '../models/skill_params.dart';
+
+/// Base command for operations that read skills from a YAML file.
+abstract class BaseYamlCommand extends Command<void> {
+  /// Creates a new [BaseYamlCommand].
+  BaseYamlCommand({required this.logger, this.outputDir}) {
+    argParser
+      ..addOption('skill', help: 'Process only the specified skill by name.')
+      ..addOption(
+        'directory',
+        abbr: 'd',
+        help: 'The directory to search for skills.',
+      );
+  }
+
+  /// The logger for this command.
+  final Logger logger;
+
+  /// The directory to find generated skills.
+  final Directory? outputDir;
+
+  @override
+  Future<void> run() async {
+    final inputFile = argResults!.rest.isNotEmpty
+        ? argResults!.rest.first
+        : 'resources/flutter_skills.yaml';
+
+    final file = File(inputFile);
+    if (!file.existsSync()) {
+      logger.severe('Configuration file not found: $inputFile');
+      return;
+    }
+
+    final yamlContent = file.readAsStringSync();
+    final yamlList = loadYaml(yamlContent) as YamlList;
+    final skills = yamlList
+        .map(
+          (e) => SkillParams.fromJson(
+            jsonDecode(jsonEncode(e)) as Map<String, dynamic>,
+          ),
+        )
+        .toList();
+
+    final skillFilter = argResults?['skill'] as String?;
+    final targetSkills = skillFilter != null
+        ? skills.where((s) => s.name == skillFilter).toList()
+        : skills;
+
+    if (targetSkills.isEmpty) {
+      if (skillFilter != null) {
+        logger.warning('No skill found with name: $skillFilter');
+      } else {
+        logger.warning('No skills found in configuration file.');
+      }
+      return;
+    }
+
+    final directoryArg = argResults?['directory'] as String?;
+    final outDir = directoryArg != null
+        ? Directory(directoryArg)
+        : (outputDir ?? Directory('skills'));
+
+    await runWithSkills(targetSkills, outDir, configDir: file.parent);
+  }
+
+  /// Executes the command with the parsed and filtered list of skills.
+  Future<void> runWithSkills(
+    List<SkillParams> skills,
+    Directory outputDir, {
+    Directory? configDir,
+  });
+}

package/skills/flutter-skills/tool/generator/lib/src/commands/generate_skill_command.dart

@@ -0,0 +1,92 @@
+// 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:io';
+
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+
+import '../models/skill_params.dart';
+import '../services/gemini_service.dart';
+import '../services/resource_fetcher_service.dart';
+import 'base_skill_command.dart';
+
+/// Command to generate skills from a configuration file.
+class GenerateSkillCommand extends BaseSkillCommand {
+  /// Creates a new [GenerateSkillCommand].
+  GenerateSkillCommand({
+    required super.httpClient,
+    super.outputDir,
+    super.environment,
+  }) : super(logger: Logger('GenerateSkillCommand'));
+
+  @override
+  String get name => 'generate-skill';
+
+  @override
+  String get description => 'Generates skills from using yaml configuration.';
+
+  @override
+  Future<void> runSkill(
+    SkillParams skill,
+    GeminiService gemini,
+    Directory outputDir,
+    int thinkingBudget, {
+    Directory? configDir,
+  }) async {
+    logger.info('Generating skill: ${skill.name}...');
+
+    try {
+      final fetcher = ResourceFetcherService(
+        httpClient: httpClient,
+        logger: logger,
+      );
+      final combinedMarkdown = await fetcher.fetchAndConvertContent(
+        skill.resources,
+        configDir: configDir,
+      );
+
+      if (combinedMarkdown.isEmpty) {
+        logger.warning('  No content fetched for ${skill.name}. Skipping.');
+        return;
+      }
+
+      final dryRun = argResults?['dry-run'] as bool? ?? false;
+      if (dryRun) {
+        logger
+          ..info('  [DRY RUN] Would generate skill: ${skill.name}')
+          ..info(
+            '  [DRY RUN] Prompt size: ${combinedMarkdown.split(' ').length} tokens.',
+          );
+        return;
+      }
+
+      final generatedContent = await gemini.generateSkillContent(
+        combinedMarkdown,
+        skill.name,
+        skill.description,
+        instructions: skill.instructions,
+        thinkingBudget: thinkingBudget,
+      );
+
+      if (generatedContent != null && generatedContent.isNotEmpty) {
+        final skillDir = Directory(p.join(outputDir.path, skill.name));
+        if (!skillDir.existsSync()) {
+          skillDir.createSync(recursive: true);
+        }
+
+        File(
+          p.join(skillDir.path, 'SKILL.md'),
+        ).writeAsStringSync(generatedContent);
+        logger.info(
+          '  Generated ${p.join(outputDir.path, skill.name, 'SKILL.md')}',
+        );
+      } else {
+        logger.severe('  Failed to generate content for ${skill.name}');
+      }
+    } on Exception catch (e) {
+      logger.severe('  Error processing ${skill.name}: $e');
+    }
+  }
+}