Merge pull request #33 from flutter/update-skill-readme

Update READMEs

Author: johnpryan

README.md

@@ -1,11 +1,57 @@
 # Agent Skills for Flutter
 
+**NOTE: This repository is currently in development and is not yet ready for use.**
+
 This repository contains agent skills for Flutter.
 
+## Installation
+
+To install the skills into your project, run the following command:
+
+```bash
+npx skills add flutter/skills
+```
+
+## Updating Skills
+
+To update, run the following command:
+
+```bash
+npx skills update flutter/skills
+```
+
+## Available Skills
+
+| Skill | Description |
+|---|---|
+| [flutter-accessibility](skills/flutter-accessibility/SKILL.md) | Configure your Flutter app to support assistive technologies like Screen Readers |
+| [flutter-animation](skills/flutter-animation/SKILL.md) | Add animated effects to your Flutter app |
+| [flutter-app-size](skills/flutter-app-size/SKILL.md) | Measure and reduce the size of the Flutter app bundle, APK, or IPA |
+| [flutter-architecture](skills/flutter-architecture/SKILL.md) | Build an app using the Flutter team's recommended app architecture |
+| [flutter-caching](skills/flutter-caching/SKILL.md) | Cache data in a Flutter app |
+| [flutter-concurrency](skills/flutter-concurrency/SKILL.md) | Execute long-running tasks in a background thread in Flutter |
+| [flutter-databases](skills/flutter-databases/SKILL.md) | Work with databases in a Flutter app |
+| [flutter-environment-setup-linux](skills/flutter-environment-setup-linux/SKILL.md) | Set up a Linux environment for Flutter development |
+| [flutter-environment-setup-macos](skills/flutter-environment-setup-macos/SKILL.md) | Set up a macOS environment for Flutter development |
+| [flutter-environment-setup-windows](skills/flutter-environment-setup-windows/SKILL.md) | Set up a Windows environment for Flutter development |
+| [flutter-http-and-json](skills/flutter-http-and-json/SKILL.md) | Make HTTP requests and encode / decode JSON in a Flutter app |
+| [flutter-layout](skills/flutter-layout/SKILL.md) | How to build your app's layout using Flutter's layout widgets and constraint system |
+| [flutter-localization](skills/flutter-localization/SKILL.md) | Configure your Flutter app to support different languages and regions |
+| [flutter-native-interop](skills/flutter-native-interop/SKILL.md) | Interoperate with native APIs in a Flutter app on Android, iOS, and the web |
+| [flutter-performance](skills/flutter-performance/SKILL.md) | Optimize the performance of your Flutter app |
+| [flutter-platform-views](skills/flutter-platform-views/SKILL.md) | Add a native view into your Flutter app |
+| [flutter-plugins](skills/flutter-plugins/SKILL.md) | Build a Flutter plugin that provides native interop for other Flutter apps to use |
+| [flutter-routing-and-navigation](skills/flutter-routing-and-navigation/SKILL.md) | Move between or deep link to different screens or routes within a Flutter application |
+| [flutter-state-management](skills/flutter-state-management/SKILL.md) | Manage state in your Flutter application |
+| [flutter-testing](skills/flutter-testing/SKILL.md) | Add Flutter unit tests, widget tests, or integration tests |
+| [flutter-theming](skills/flutter-theming/SKILL.md) | How to customize your app's theme using Flutter's theming system |
+
 ## Contributing
 
+To contribute skills, see the instructions in [tool/README.md](tool/README.md).
+
 Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
 
 ## Code of Conduct
 
-Please see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for more information.
+Please see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for more information.

tool/README.md

@@ -28,47 +28,65 @@ dart run skills generate-skill [options] [config_file]
 *   `--skill`: Filter to generate only the specified skill by name.
 *   `--directory` (`-d`): The directory to output the generated skill folder. Defaults to `../skills/`.
 
-### `validate-skill`
+**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:
 
-Validates skills by re-generating and comparing with existing skills.
+```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 validate-skill [options] [config_file]
+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`: Validate only the specified skill by name.
-*   `--directory` (`-d`): The directory containing the generated skills. Defaults to the output directory or `../skills/`.
+*   `--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:**
-Generate all skills defined in resources/flutter_skills.yaml to the skills/ directory:
+Update all skills defined in resources/flutter_skills.yaml:
 
 ```bash
-dart run skills generate-skill
+dart run skills update-skill
 ```
 
-Generate only the 'flutter-layout' skill to a custom directory:
+Update only the 'flutter-layout' skill:
 
-```
-dart run skills generate-skill --skill flutter-layout --directory ../skills
+```bash
+dart run skills update-skill --skill flutter-layout
 ```
 
 ### `validate-skill`
 
-Validates generated skills by re-generating them using the same source and comparing the output. This is useful for testing prompts or verifying consistency.
+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]
+dart run skills validate-skill [options] [config_file]
 ```
 
+**Arguments:**
+*   `[config_file]`: Path to the YAML configuration file. Defaults to `resources/flutter_skills.yaml`.
+
 **Options:**
-*   `--directory` (`-d`): The directory containing the generated skills to validate. Defaults to `skills/`.
+*   `--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:
@@ -78,10 +96,31 @@ 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 `tool/resources/flutter_skills.yaml`. It contains a list of skill definitions:

tool/bin/skills.dart

@@ -8,6 +8,7 @@ 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';
 
@@ -20,7 +21,8 @@ void main(List<String> arguments) async {
       CommandRunner<void>('skills', 'A sample command-line application.')
         ..addCommand(GenerateSkillCommand(httpClient: httpClient))
         ..addCommand(UpdateSkillCommand(httpClient: httpClient))
-        ..addCommand(ValidateSkillCommand(httpClient: httpClient));
+        ..addCommand(ValidateSkillCommand(httpClient: httpClient))
+        ..addCommand(UpdateReadmeCommand());
 
   runner.argParser.addFlag(
     'version',

tool/lib/src/commands/base_skill_command.dart

@@ -2,100 +2,50 @@
 // 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:logging/logging.dart';
-import 'package:yaml/yaml.dart';
 
 import '../models/skill_params.dart';
 import '../services/gemini_service.dart';
+import 'base_yaml_command.dart';
 
-/// Base command for skill operations.
-abstract class BaseSkillCommand extends Command<void> {
+/// Base command for skill operations requiring AI generation.
+abstract class BaseSkillCommand extends BaseYamlCommand {
   /// Creates a new [BaseSkillCommand].
   BaseSkillCommand({
     required this.httpClient,
-    required this.logger,
-    this.outputDir,
+    required super.logger,
+    super.outputDir,
     this.environment,
   }) {
-    argParser
-      ..addOption('skill', help: 'Process only the specified skill by name.')
-      ..addOption(
-        'directory',
-        abbr: 'd',
-        help: 'The directory to output/search for skills.',
-      )
-      ..addOption(
-        'thinking-budget',
-        help:
-            'The token budget for the model to "think". Defaults to ${GeminiService.defaultThinkingBudget} (recommended for technical documentation).',
-        defaultsTo: GeminiService.defaultThinkingBudget.toString(),
-      );
+    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(),
+    );
   }
 
   /// The HTTP client used for fetching resources.
   final http.Client httpClient;
 
-  /// The directory to output or find generated skills.
-  final Directory? outputDir;
-
   /// Optional override for the environment variables, for testing.
   final Map<String, String>? environment;
 
-  /// The logger for this command.
-  final Logger logger;
-
   @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;
-    }
-
+  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);
-    final directoryArg = argResults?['directory'] as String?;
-    final outDir = directoryArg != null
-        ? Directory(directoryArg)
-        : (outputDir ?? Directory('../skills'));
 
     int thinkingBudget;
     try {
@@ -107,13 +57,13 @@ abstract class BaseSkillCommand extends Command<void> {
       return;
     }
 
-    for (final skill in targetSkills) {
+    for (final skill in skills) {
       await runSkill(
         skill,
         gemini,
-        outDir,
+        outputDir,
         thinkingBudget,
-        configDir: file.parent,
+        configDir: configDir,
       );
     }
   }