Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions tool/generator/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:**
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
13 changes: 12 additions & 1 deletion tool/generator/lib/src/commands/base_skill_command.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 {
Expand Down
13 changes: 12 additions & 1 deletion tool/generator/lib/src/commands/generate_skill_command.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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;
}
Expand All @@ -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}');
}
Expand Down
15 changes: 14 additions & 1 deletion tool/generator/lib/src/commands/update_skill_command.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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;
}
Expand All @@ -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}');
}
Expand Down
25 changes: 24 additions & 1 deletion tool/generator/lib/src/commands/validate_skill_command.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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(
Expand All @@ -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;
}
Expand Down
46 changes: 42 additions & 4 deletions tool/generator/lib/src/services/gemini_service.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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<SafetySetting> defaultSafetySettings = [
Expand Down Expand Up @@ -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
Expand All @@ -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(
Expand Down
3 changes: 2 additions & 1 deletion tool/generator/lib/src/services/prompts.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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' : ''}

Expand All @@ -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' : ''}

Expand Down
18 changes: 9 additions & 9 deletions tool/generator/lib/src/services/skill_instructions.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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.
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 `<details>` 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).
Expand Down
9 changes: 9 additions & 0 deletions tool/generator/test/commands/base_skill_command_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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,
);
});
});
}
Loading
Loading