diff --git a/tool/generator/README.md b/tool/generator/README.md index ff3f022d..60458a52 100644 --- a/tool/generator/README.md +++ b/tool/generator/README.md @@ -4,7 +4,8 @@ The Skills CLI simplifies the process of creating "Agent Skills" from external d ## Context -* [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) +* [Agent Skills Overview](https://agentskills.io/home) +* [Agent Skills Best Practices](https://agentskills.io/skill-creation/best-practices) ## Prerequisite @@ -31,6 +32,8 @@ dart run skills generate-skill [options] [config_file] **Options:** * `--skill`: Filter to generate only the specified skill by name. * `--directory` (`-d`): The directory to output the generated skill folder. Defaults to `../skills/`. +* `--model`: The Gemini model to use for generation. Defaults to `models/gemini-4-argon`. +* `--thinking-budget`: The token budget for the model to "think" before generating content. Defaults to 4096. * `--dry-run`: Performs a dry run, showing what would be generated and token count without writing files. **Example:** @@ -61,7 +64,8 @@ dart run skills update-skill [options] [config_file] **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. +* `--model`: The Gemini model to use for generation. Defaults to `models/gemini-4-argon`. +* `--thinking-budget`: The token budget for the model to "think" before generating content. Defaults to 4096. **Example:** Update all skills defined in resources/flutter_skills.yaml: @@ -91,7 +95,8 @@ dart run skills validate-skill [options] [config_file] **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. +* `--model`: The Gemini model to use for generation. Defaults to `models/gemini-4-argon`. +* `--thinking-budget`: The token budget for the model to "think" before generating content. Defaults to 4096. **Example:** Validate skills in the default 'skills' directory: diff --git a/tool/generator/lib/src/commands/base_skill_command.dart b/tool/generator/lib/src/commands/base_skill_command.dart index 52ca0ad7..9f37850e 100644 --- a/tool/generator/lib/src/commands/base_skill_command.dart +++ b/tool/generator/lib/src/commands/base_skill_command.dart @@ -20,6 +20,12 @@ abstract class BaseSkillCommand extends BaseYamlCommand { this.environment, }) { argParser + ..addOption( + 'model', + help: + 'The Gemini model to use for generation. Defaults to ${GeminiService.defaultModel}.', + defaultsTo: GeminiService.defaultModel, + ) ..addOption( 'thinking-budget', help: @@ -53,7 +59,12 @@ abstract class BaseSkillCommand extends BaseYamlCommand { return; } - final gemini = GeminiService(apiKey: apiKey, httpClient: httpClient); + final model = argResults?['model'] as String?; + final gemini = GeminiService( + apiKey: apiKey, + httpClient: httpClient, + model: model, + ); int thinkingBudget; try { diff --git a/tool/generator/lib/src/commands/generate_skill_command.dart b/tool/generator/lib/src/commands/generate_skill_command.dart index 4cea1d26..827600c3 100644 --- a/tool/generator/lib/src/commands/generate_skill_command.dart +++ b/tool/generator/lib/src/commands/generate_skill_command.dart @@ -2,6 +2,7 @@ // 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:logging/logging.dart'; @@ -54,10 +55,12 @@ class GenerateSkillCommand extends BaseSkillCommand { final dryRun = argResults?['dry-run'] as bool? ?? false; if (dryRun) { + final words = RegExp(r'\S+').allMatches(combinedMarkdown).length; + final approxTokens = (words * 1.3).round(); logger ..info(' [DRY RUN] Would generate skill: ${skill.name}') ..info( - ' [DRY RUN] Prompt size: ${combinedMarkdown.split(' ').length} tokens.', + ' [DRY RUN] Prompt size: ~$words words (approx. $approxTokens tokens).', ); return; } @@ -82,6 +85,14 @@ class GenerateSkillCommand extends BaseSkillCommand { logger.info( ' Generated ${p.join(outputDir.path, skill.name, 'SKILL.md')}', ); + + final lineCount = const LineSplitter().convert(generatedContent).length; + if (lineCount > 500) { + logger.warning( + ' Warning: Generated SKILL.md has $lineCount lines. ' + 'The Agent Skills standard (https://agentskills.io) recommends keeping SKILL.md under 500 lines.', + ); + } } else { logger.severe(' Failed to generate content for ${skill.name}'); } diff --git a/tool/generator/lib/src/commands/update_skill_command.dart b/tool/generator/lib/src/commands/update_skill_command.dart index d272605c..23129cd3 100644 --- a/tool/generator/lib/src/commands/update_skill_command.dart +++ b/tool/generator/lib/src/commands/update_skill_command.dart @@ -2,6 +2,7 @@ // 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:logging/logging.dart'; @@ -65,10 +66,14 @@ class UpdateSkillCommand extends BaseSkillCommand { final dryRun = argResults?['dry-run'] as bool? ?? false; if (dryRun) { + final origWords = RegExp(r'\S+').allMatches(existingContent).length; + final origTokens = (origWords * 1.3).round(); + final rawWords = RegExp(r'\S+').allMatches(combinedMarkdown).length; + final rawTokens = (rawWords * 1.3).round(); logger ..info(' [DRY RUN] Would update skill: ${skill.name}') ..info( - ' [DRY RUN] Original file size: ${existingContent.split(' ').length} tokens -> Raw content size: ${combinedMarkdown.split(' ').length} tokens.', + ' [DRY RUN] Original file size: ~$origWords words (~$origTokens tokens) -> Raw content size: ~$rawWords words (~$rawTokens tokens).', ); return; } @@ -87,6 +92,14 @@ class UpdateSkillCommand extends BaseSkillCommand { logger.info( ' Updated ${p.join(outputDir.path, skill.name, 'SKILL.md')}', ); + + final lineCount = const LineSplitter().convert(generatedContent).length; + if (lineCount > 500) { + logger.warning( + ' Warning: Updated SKILL.md has $lineCount lines. ' + 'The Agent Skills standard (https://agentskills.io) recommends keeping SKILL.md under 500 lines.', + ); + } } else { logger.severe(' Failed to update content for ${skill.name}'); } diff --git a/tool/generator/lib/src/commands/validate_skill_command.dart b/tool/generator/lib/src/commands/validate_skill_command.dart index 37f87868..31885181 100644 --- a/tool/generator/lib/src/commands/validate_skill_command.dart +++ b/tool/generator/lib/src/commands/validate_skill_command.dart @@ -2,6 +2,7 @@ // 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:logging/logging.dart'; @@ -102,6 +103,11 @@ class ValidateSkillCommand extends BaseSkillCommand { } else if (rawDescription is! String) { logger.severe('Skill "$name" field "description" must be a string.'); isValid = false; + } else if (rawDescription.length > 1024) { + logger.warning( + 'Skill "$name" description exceeds 1024 characters (${rawDescription.length} chars). ' + 'The Agent Skills standard (https://agentskills.io) limits descriptions to 1024 characters.', + ); } if (item['resources'] == null) { @@ -221,6 +227,17 @@ class ValidateSkillCommand extends BaseSkillCommand { ); } + // Check file length per agentskills.io recommendation (< 500 lines) + final lineCount = const LineSplitter() + .convert(existingSkillFileContent) + .length; + if (lineCount > 500) { + logger.warning( + ' Validation Warning: ${existingSkillFile.path} has $lineCount lines. ' + 'The Agent Skills standard (https://agentskills.io) recommends keeping SKILL.md under 500 lines.', + ); + } + // Extract metadata from existing content final generationDate = RegExp( @@ -236,10 +253,16 @@ class ValidateSkillCommand extends BaseSkillCommand { // Compare final dryRun = argResults?['dry-run'] as bool? ?? false; if (dryRun) { + final existWords = RegExp( + r'\S+', + ).allMatches(existingSkillFileContent).length; + final existTokens = (existWords * 1.3).round(); + final rawWords = RegExp(r'\S+').allMatches(markdown).length; + final rawTokens = (rawWords * 1.3).round(); logger ..info(' [DRY RUN] Would validate skill: ${skill.name}') ..info( - ' [DRY RUN] existing file size: ${existingSkillFileContent.split(' ').length} tokens -> new fetched content size: ${markdown.split(' ').length} tokens.', + ' [DRY RUN] Existing file size: ~$existWords words (~$existTokens tokens) -> Fetched content size: ~$rawWords words (~$rawTokens tokens).', ); return; } diff --git a/tool/generator/lib/src/services/gemini_service.dart b/tool/generator/lib/src/services/gemini_service.dart index 27ce3f7b..83fed1ff 100644 --- a/tool/generator/lib/src/services/gemini_service.dart +++ b/tool/generator/lib/src/services/gemini_service.dart @@ -23,17 +23,50 @@ class GeminiService { }) : _model = model ?? defaultModel, _client = _ApiKeyClient(httpClient ?? http.Client(), apiKey); - /// 0.2 is a good temperature for technical material. + /// Default temperature for legacy models. + /// + /// Note: For Gemini 4 models (such as `gemini-4-argon`), sampling parameters + /// such as temperature, top_p, and top_k should be omitted, as the model + /// optimizes its own reasoning path and setting them can degrade performance + /// or is ignored by the API. + /// + /// See: https://ai.google.dev/gemini-api/docs/latest-model#migrate-to-gemini-4-argon static const double defaultTemperature = 0.2; /// The default model to use for generation. - static const String defaultModel = 'models/gemini-3.1-pro-preview'; + /// + /// Defaults to Gemini 4 Argon (`models/gemini-4-argon`), Google's flagship + /// model for software engineering, deep reasoning, and autonomous agents, + /// featuring a 1M unified context window. + /// + /// See: + /// - https://ai.google.dev/gemini-api/docs/models/gemini-4-argon + /// - https://ai.google.dev/gemini-api/docs/latest-model + static const String defaultModel = 'models/gemini-4-argon'; /// The default token budget for thinking. + /// + /// Gemini 4 Argon engages in dynamic reasoning by default (using thinking + /// levels: low, medium, high). When communicating via GenerativeLanguage API, + /// thinking budget controls reasoning depth. + /// + /// See: + /// - https://ai.google.dev/gemini-api/docs/thinking + /// - https://ai.google.dev/gemini-api/docs/latest-model#understanding-thinking-levels static const int defaultThinkingBudget = 4096; /// The default max output tokens for generation. - static const int defaultMaxOutputLimit = 8192; + /// + /// For Gemini 4 Argon (and thinking models), thinking tokens and response + /// tokens share the same output budget and context window. In synchronous + /// mode, Gemini 4 Argon supports a maximum output limit of 65,536 tokens. + /// Setting a limit lower than 32K (such as 8192) can cause reasoning to be + /// truncated. + /// + /// See: + /// - https://ai.google.dev/gemini-api/docs/models/gemini-4-argon + /// - https://ai.google.dev/gemini-api/docs/latest-model#setting-output-token-limits + static const int defaultMaxOutputLimit = 65536; /// The default safety settings to use for generation. static final List defaultSafetySettings = [ @@ -272,6 +305,11 @@ metadata: String? systemInstruction, int thinkingBudget = defaultThinkingBudget, }) { + // For Gemini 4 thinking models, sampling parameters (temperature, top_p, + // top_k) should be omitted per Google best practices. + final isGemini4 = + _model.startsWith('models/gemini-4') || _model.startsWith('gemini-4'); + return GenerateContentRequest( model: _model, systemInstruction: systemInstruction != null @@ -282,7 +320,7 @@ metadata: ], // See [GenerationConfig] in package:google_cloud_ai_generativelanguage_v1beta generationConfig: GenerationConfig( - temperature: defaultTemperature, + temperature: isGemini4 ? null : defaultTemperature, maxOutputTokens: defaultMaxOutputLimit, thinkingConfig: thinkingBudget > 0 ? ThinkingConfig( diff --git a/tool/generator/lib/src/services/prompts.dart b/tool/generator/lib/src/services/prompts.dart index dfa4a87d..13b415ef 100644 --- a/tool/generator/lib/src/services/prompts.dart +++ b/tool/generator/lib/src/services/prompts.dart @@ -10,6 +10,7 @@ class Prompts { static String createSkillPrompt(String markdown, String? instructions) { return ''' Rewrite the following technical documentation into a high-quality "SKILL.md" file. +Synthesize the essential procedures into a concise, focused document strictly under 500 lines and between 1,500 and 3,500 tokens (never exceed 5,000 tokens). Omit basic introductory concepts that competent AI agents already know. ${instructions != null && instructions.isNotEmpty ? 'Special Instructions: $instructions' : ''} @@ -26,7 +27,7 @@ $markdown ) { return ''' Update the following existing "SKILL.md" file using the provided new technical documentation. -Carefully integrate the new information without losing valuable existing instructions or context. +Carefully integrate the new information without losing valuable existing instructions or context, keeping the final output concise, high-density, and strictly under 500 lines. ${instructions != null && instructions.isNotEmpty ? 'Special Instructions: $instructions' : ''} diff --git a/tool/generator/lib/src/services/skill_instructions.dart b/tool/generator/lib/src/services/skill_instructions.dart index c26977ba..0dec6efc 100644 --- a/tool/generator/lib/src/services/skill_instructions.dart +++ b/tool/generator/lib/src/services/skill_instructions.dart @@ -5,18 +5,18 @@ /// 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. +Act as an Expert Skill Author. Generate high-performance, well-structured Skill modules (SKILL.md) that conform to the Agent Skills open standard (https://agentskills.io). # 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. +1. **Concise & Expert:** Assume the AI agent is highly competent. Only provide context the agent doesn't already have. Challenge each paragraph: "Does this justify its token cost?". Avoid explaining basic concepts or introductory overviews. 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
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
tags to collapse lengthy reference material if it exceeds 500 lines. +3. **Optimum Size & Line Limit:** Strictly keep `SKILL.md` under 500 lines and between 1,500 and 3,500 tokens (never exceed 5,000 tokens). Every token in the skill competes for the agent's context window on every run. +4. **Single File Constraint:** Do not use external file references (e.g., `[other.md](other.md)`). Include all essential procedural content directly within the `SKILL.md` file. Do not use `
` HTML tags. +5. **Naming:** Use the gerund form (verb + -ing) for the H1 title. +6. **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. +7. **Conditional Logic:** Use conditional workflows to guide the agent through decision points (e.g., "If creating NEW content..." vs "If EDITING existing content..."). +8. **Examples & Defaults:** When output quality depends on style or specific formatting, provide clear input/output pairs or high-fidelity implementation examples. Provide clear defaults rather than open-ended menus of choices. +9. **Consistent Terminology:** Choose one clear term for concepts (e.g., "API endpoint", "Widget state") and use it throughout. # 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). diff --git a/tool/generator/test/commands/base_skill_command_test.dart b/tool/generator/test/commands/base_skill_command_test.dart index 473129c5..48edfbf4 100644 --- a/tool/generator/test/commands/base_skill_command_test.dart +++ b/tool/generator/test/commands/base_skill_command_test.dart @@ -127,5 +127,14 @@ void main() { expect(logs, contains('GEMINI_API_KEY environment variable not set.')); }); + + test('defines model option defaulting to GeminiService.defaultModel', () { + final command = _TestSkillCommand(httpClient: mockClient); + expect(command.argParser.options.containsKey('model'), isTrue); + expect( + command.argParser.options['model']!.defaultsTo, + GeminiService.defaultModel, + ); + }); }); } diff --git a/tool/generator/test/generate_skills_test.dart b/tool/generator/test/generate_skills_test.dart index 0df99dea..65216a73 100644 --- a/tool/generator/test/generate_skills_test.dart +++ b/tool/generator/test/generate_skills_test.dart @@ -246,7 +246,7 @@ void main() { logs, contains( contains( - 'Model: models/gemini-3.1-pro-preview, Max Output Tokens: 8192, Thinking Budget: 4000', + 'Model: models/gemini-4-argon, Max Output Tokens: 65536, Thinking Budget: 4000', ), ), ); @@ -260,6 +260,76 @@ void main() { ); }); + test('accepts custom --model option', () async { + final skillsDir = Directory(p.join(tempDir.path, 'skills_output_model')); + await skillsDir.create(); + + final configFile = File(p.join(tempDir.path, 'config_model.yaml')); + final inputData = [ + { + 'name': 'model_test', + 'description': 'Model test description', + 'resources': ['https://example.com/model'], + }, + ]; + configFile.writeAsStringSync(jsonEncode(inputData)); + + final logs = []; + final sub = Logger.root.onRecord.listen((record) { + logs.add(record.message); + }); + addTearDown(sub.cancel); + + final mockClient = MockClient((request) async { + final url = request.url.toString(); + if (url == 'https://example.com/model') { + return http.Response('Model Content', 200); + } + if (url.contains('generativelanguage')) { + return http.Response( + jsonEncode({ + 'candidates': [ + { + 'content': { + 'parts': [ + {'text': 'Generated Model Content'}, + ], + }, + }, + ], + }), + 200, + ); + } + return http.Response('Error', 500); + }); + + final command = GenerateSkillCommand( + environment: {'GEMINI_API_KEY': 'test-key'}, + httpClient: mockClient, + outputDir: skillsDir, + ); + runner.addCommand(command); + + await runner.run([ + 'generate-skill', + configFile.path, + '--directory', + skillsDir.path, + '--model', + 'models/custom-model-test', + ]); + + expect( + logs, + contains( + contains( + 'Model: models/custom-model-test, Max Output Tokens: 65536, Thinking Budget: 4096', + ), + ), + ); + }); + test('handles invalid thinking-budget option gracefully', () async { final skillsDir = await Directory.systemTemp.createTemp('skills_output'); addTearDown(() => skillsDir.delete(recursive: true)); @@ -511,6 +581,12 @@ void main() { logs, contains(contains('[DRY RUN] Would generate skill: dry-run-skill')), ); + expect( + logs, + contains( + contains('[DRY RUN] Prompt size: ~7 words (approx. 9 tokens).'), + ), + ); final skillDir = Directory(p.join(tempDir.path, 'dry-run-skill')); expect(skillDir.existsSync(), isFalse); diff --git a/tool/generator/test/services/gemini_service_test.dart b/tool/generator/test/services/gemini_service_test.dart index a274533b..d49c6401 100644 --- a/tool/generator/test/services/gemini_service_test.dart +++ b/tool/generator/test/services/gemini_service_test.dart @@ -287,5 +287,112 @@ Some content expect(result, isNot(contains('model: "models/test-model"'))); }); }); + + group('Gemini 4 request parameters', () { + test( + 'omits temperature for models starting with models/gemini-4', + () async { + late Map capturedBody; + final mockClient = MockClient((request) async { + capturedBody = jsonDecode(request.body) as Map; + return http.Response( + jsonEncode({ + 'candidates': [ + { + 'content': { + 'parts': [ + {'text': 'Generated content'}, + ], + }, + }, + ], + }), + 200, + ); + }); + + final gemini = GeminiService( + apiKey: 'test-key', + httpClient: mockClient, + model: 'models/gemini-4-argon', + ); + + await gemini.generateSkillContent('raw', 'name', 'desc'); + + final genConfig = + capturedBody['generationConfig'] as Map; + expect(genConfig.containsKey('temperature'), isFalse); + }, + ); + + test( + 'omits temperature for models starting with gemini-4 without prefix', + () async { + late Map capturedBody; + final mockClient = MockClient((request) async { + capturedBody = jsonDecode(request.body) as Map; + return http.Response( + jsonEncode({ + 'candidates': [ + { + 'content': { + 'parts': [ + {'text': 'Generated content'}, + ], + }, + }, + ], + }), + 200, + ); + }); + + final gemini = GeminiService( + apiKey: 'test-key', + httpClient: mockClient, + model: 'gemini-4-argon', + ); + + await gemini.generateSkillContent('raw', 'name', 'desc'); + + final genConfig = + capturedBody['generationConfig'] as Map; + expect(genConfig.containsKey('temperature'), isFalse); + }, + ); + + test('includes temperature for non-gemini-4 models', () async { + late Map capturedBody; + final mockClient = MockClient((request) async { + capturedBody = jsonDecode(request.body) as Map; + return http.Response( + jsonEncode({ + 'candidates': [ + { + 'content': { + 'parts': [ + {'text': 'Generated content'}, + ], + }, + }, + ], + }), + 200, + ); + }); + + final gemini = GeminiService( + apiKey: 'test-key', + httpClient: mockClient, + model: 'models/gemini-3.1-pro-preview', + ); + + await gemini.generateSkillContent('raw', 'name', 'desc'); + + final genConfig = + capturedBody['generationConfig'] as Map; + expect(genConfig['temperature'], equals(0.2)); + }); + }); }); } diff --git a/tool/generator/test/update_skills_test.dart b/tool/generator/test/update_skills_test.dart index d1f8ce48..4c9680e4 100644 --- a/tool/generator/test/update_skills_test.dart +++ b/tool/generator/test/update_skills_test.dart @@ -235,6 +235,14 @@ void main() { logs, contains(contains('[DRY RUN] Would update skill: dry-update')), ); + expect( + logs, + contains( + contains( + '[DRY RUN] Original file size: ~2 words (~3 tokens) -> Raw content size: ~8 words (~10 tokens).', + ), + ), + ); expect(skillFile.readAsStringSync(), equals('Existing content')); }); }); diff --git a/tool/generator/test/validate_skills_test.dart b/tool/generator/test/validate_skills_test.dart index c749c942..30d7a336 100644 --- a/tool/generator/test/validate_skills_test.dart +++ b/tool/generator/test/validate_skills_test.dart @@ -261,6 +261,90 @@ void main() { expect(logs, contains(contains('Existing skill file not found'))); }); + test('logs warning when existing skill file exceeds 500 lines', () async { + const skillName = 'long-skill'; + final skillDir = Directory(p.join(skillsDir.path, skillName)); + await skillDir.create(); + final longContent = StringBuffer('---\nname: $skillName\n---\n'); + for (var i = 0; i < 505; i++) { + longContent.writeln('Line $i'); + } + File( + p.join(skillDir.path, 'SKILL.md'), + ).writeAsStringSync(longContent.toString()); + + final configFile = File(p.join(tempDir.path, 'config_long.yaml')); + await configFile.writeAsString( + jsonEncode([ + { + 'name': skillName, + 'description': 'Desc', + 'resources': ['https://example.com'], + }, + ]), + ); + + final mockClient = MockClient((request) async { + return http.Response('Content', 200); + }); + + runner = CommandRunner('skills', 'Test runner') + ..addCommand( + ValidateSkillCommand( + environment: {'GEMINI_API_KEY': 'test-key'}, + outputDir: skillsDir, + httpClient: mockClient, + ), + ); + + await IOOverrides.runZoned(() async { + await runner.run(['validate-skill', '--dry-run', configFile.path]); + }, getCurrentDirectory: () => tempDir); + + expect( + logs, + contains( + contains( + 'The Agent Skills standard (https://agentskills.io) recommends keeping SKILL.md under 500 lines.', + ), + ), + ); + }); + + test('logs warning when description exceeds 1024 characters', () async { + const skillName = 'long-desc-skill'; + final configFile = File(p.join(tempDir.path, 'config_long_desc.yaml')); + final longDesc = 'A' * 1050; + await configFile.writeAsString( + jsonEncode([ + { + 'name': skillName, + 'description': longDesc, + 'resources': ['https://example.com'], + }, + ]), + ); + + final mockClient = MockClient((request) async { + return http.Response('Content', 200); + }); + + runner = CommandRunner('skills', 'Test runner') + ..addCommand( + ValidateSkillCommand( + environment: {'GEMINI_API_KEY': 'test-key'}, + outputDir: skillsDir, + httpClient: mockClient, + ), + ); + + await IOOverrides.runZoned(() async { + await runner.run(['validate-skill', '--dry-run', configFile.path]); + }, getCurrentDirectory: () => tempDir); + + expect(logs, contains(contains('description exceeds 1024 characters'))); + }); + test('logs warning when failed to fetch URL', () async { const skillName = 'fail-skill'; final skillDir = Directory(p.join(skillsDir.path, skillName)); @@ -716,6 +800,14 @@ Content logs, contains(contains('[DRY RUN] Would validate skill: $skillName')), ); + expect( + logs, + contains( + contains( + '[DRY RUN] Existing file size: ~4 words (~5 tokens) -> Fetched content size: ~8 words (~10 tokens).', + ), + ), + ); final valDir = Directory(p.join(validationDir.path, skillName)); expect(valDir.existsSync(), isFalse);