openskill-ai 1.0.0

package/skills/flutter-skills/rules/dart-avoid-dynamic.md

@@ -0,0 +1,86 @@
+---
+title: Avoid Dynamic Types
+impact: LOW-MEDIUM
+impactDescription: Enables AOT optimization, catches errors
+tags: dart, types, dynamic, safety
+---
+
+## Avoid Dynamic Types
+
+Avoid `dynamic` type to enable compiler optimizations and catch errors at compile time.
+
+**Incorrect (dynamic defeats type checking):**
+
+```dart
+dynamic fetchData() {
+  // Caller has no idea what type to expect
+  return {'name': 'John', 'age': 30};
+}
+
+void processData(dynamic data) {
+  // No autocomplete, no type safety
+  print(data.name); // Runtime error if wrong type
+  print(data.nonExistent); // No compile-time error!
+}
+
+List<dynamic> items = [1, 'two', 3.0]; // Mixed types
+```
+
+**Correct (explicit types):**
+
+```dart
+Map<String, dynamic> fetchData() {
+  return {'name': 'John', 'age': 30};
+}
+
+// Better: Use a typed model
+class User {
+  final String name;
+  final int age;
+  
+  const User({required this.name, required this.age});
+  
+  factory User.fromJson(Map<String, dynamic> json) {
+    return User(
+      name: json['name'] as String,
+      age: json['age'] as int,
+    );
+  }
+}
+
+User fetchUser() {
+  final json = {'name': 'John', 'age': 30};
+  return User.fromJson(json);
+}
+```
+
+**For JSON handling:**
+
+```dart
+// Accept dynamic at API boundary, convert immediately
+class ApiService {
+  Future<User> getUser(int id) async {
+    final response = await http.get('/users/$id');
+    final json = jsonDecode(response.body) as Map<String, dynamic>;
+    return User.fromJson(json); // Typed from here on
+  }
+}
+```
+
+**When dynamic is acceptable:**
+- JSON parsing at boundaries
+- Reflection/mirrors (rare)
+- Interop with JavaScript
+
+**Enable strict linting:**
+
+```yaml
+# analysis_options.yaml
+analyzer:
+  language:
+    strict-casts: true
+    strict-raw-types: true
+linter:
+  rules:
+    - avoid_dynamic_calls
+```

package/skills/flutter-skills/rules/dart-cascade-notation.md

@@ -0,0 +1,89 @@
+---
+title: Use Cascade Notation for Multiple Operations
+impact: LOW-MEDIUM
+impactDescription: Cleaner code, fewer intermediate variables
+tags: dart, cascade, notation, chaining
+---
+
+## Use Cascade Notation for Multiple Operations
+
+Use cascade notation (`..`) to perform multiple operations on the same object without repeating the reference.
+
+**Incorrect (repeated object reference):**
+
+```dart
+void setupController() {
+  final controller = TextEditingController();
+  controller.text = 'Initial value';
+  controller.selection = TextSelection.collapsed(offset: 0);
+  controller.addListener(onChanged);
+  return controller;
+}
+
+// Or with builder pattern feeling clunky:
+void buildRequest() {
+  final request = HttpRequest();
+  request.method = 'POST';
+  request.headers['Content-Type'] = 'application/json';
+  request.body = jsonEncode(data);
+  return request.send();
+}
+```
+
+**Correct (cascade notation):**
+
+```dart
+TextEditingController setupController() {
+  return TextEditingController()
+    ..text = 'Initial value'
+    ..selection = const TextSelection.collapsed(offset: 0)
+    ..addListener(onChanged);
+}
+
+Future<Response> buildRequest() {
+  return (HttpRequest()
+        ..method = 'POST'
+        ..headers['Content-Type'] = 'application/json'
+        ..body = jsonEncode(data))
+      .send();
+}
+```
+
+**Common use cases:**
+
+```dart
+// Paint configuration
+final paint = Paint()
+  ..color = Colors.blue
+  ..strokeWidth = 2.0
+  ..style = PaintingStyle.stroke
+  ..strokeCap = StrokeCap.round;
+
+// Path building
+final path = Path()
+  ..moveTo(0, 0)
+  ..lineTo(100, 0)
+  ..lineTo(100, 100)
+  ..close();
+
+// List population
+final items = <String>[]
+  ..add('first')
+  ..addAll(['second', 'third'])
+  ..sort();
+```
+
+**Null-aware cascade (Dart 2.12+):**
+
+```dart
+// Only cascades if object is not null
+paint
+  ?..color = Colors.red
+  ..strokeWidth = 3.0;
+```
+
+**Benefits:**
+- Less repetition
+- Cleaner initialization
+- Returns the object (unlike method calls)
+- Works great with builders

package/skills/flutter-skills/rules/dart-collection-if.md

@@ -0,0 +1,92 @@
+---
+title: Use Collection-if Instead of Conditional Logic
+impact: LOW-MEDIUM
+impactDescription: Cleaner, more performant collections
+tags: dart, collection, conditional, syntax
+---
+
+## Use Collection-if Instead of Conditional Logic
+
+Use collection-if and collection-for for cleaner dynamic lists with better performance.
+
+**Incorrect (imperative approach):**
+
+```dart
+List<Widget> buildItems(bool showHeader, bool showFooter) {
+  var items = <Widget>[];
+  
+  if (showHeader) {
+    items.add(HeaderWidget());
+  }
+  
+  items.add(MainContent());
+  
+  if (showFooter) {
+    items.add(FooterWidget());
+  }
+  
+  return items;
+}
+```
+
+**Correct (collection-if):**
+
+```dart
+List<Widget> buildItems(bool showHeader, bool showFooter) {
+  return [
+    if (showHeader) const HeaderWidget(),
+    const MainContent(),
+    if (showFooter) const FooterWidget(),
+  ];
+}
+```
+
+**In widget trees:**
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return Column(
+    children: [
+      const TitleWidget(),
+      if (isLoading) const CircularProgressIndicator(),
+      if (hasError) Text('Error: $errorMessage'),
+      if (data != null) ...[
+        DataHeader(data: data!),
+        for (final item in data!.items) ItemWidget(item: item),
+      ],
+      if (showActions) const ActionButtons(),
+    ],
+  );
+}
+```
+
+**Collection-for:**
+
+```dart
+// Incorrect
+List<Widget> buildList(List<Item> items) {
+  return items.map((item) => ItemWidget(item: item)).toList();
+}
+
+// Correct (collection-for)
+List<Widget> buildList(List<Item> items) {
+  return [
+    for (final item in items) ItemWidget(item: item),
+  ];
+}
+```
+
+**Combined usage:**
+
+```dart
+final menu = [
+  const MenuItem(title: 'Home'),
+  if (isLoggedIn) ...[
+    const MenuItem(title: 'Profile'),
+    for (final bookmark in bookmarks) 
+      MenuItem(title: bookmark.name),
+  ],
+  if (isAdmin) const MenuItem(title: 'Admin'),
+];
+```

package/skills/flutter-skills/rules/dart-final-const.md

@@ -0,0 +1,70 @@
+---
+title: Use final and const Appropriately
+impact: LOW-MEDIUM
+impactDescription: Enables compiler optimizations
+tags: dart, final, const, immutability
+---
+
+## Use final and const Appropriately
+
+Use `final` for runtime constants and `const` for compile-time constants to enable optimizations.
+
+**Incorrect (no immutability hints):**
+
+```dart
+class BadExample {
+  var name = 'John';           // Mutable - can change
+  var items = <String>[];      // Mutable list
+  var config = {'key': 'value'}; // Mutable map
+  
+  void process() {
+    var result = calculateSomething(); // Not marked final
+    print(result);
+    // result could accidentally be reassigned
+  }
+}
+```
+
+**Correct (proper const/final usage):**
+
+```dart
+class GoodExample {
+  final String name = 'John';  // Runtime immutable
+  final List<String> items;    // Reference immutable
+  
+  // Compile-time constant
+  static const defaultConfig = {'key': 'value'};
+  
+  // Const constructor enables const instances
+  const GoodExample({required this.items});
+  
+  void process() {
+    final result = calculateSomething(); // Cannot reassign
+    print(result);
+  }
+}
+
+// Usage
+const instance = GoodExample(items: ['a', 'b']); // Compile-time constant
+```
+
+**const collections:**
+
+```dart
+// Incorrect - creates new list each time
+Widget build(BuildContext context) {
+  return Row(children: [Text('A'), Text('B')]);
+}
+
+// Correct - reuses same list
+Widget build(BuildContext context) {
+  return const Row(children: [Text('A'), Text('B')]);
+}
+```
+
+**Guidelines:**
+- Use `const` for values known at compile time
+- Use `final` for values computed at runtime but never changed
+- Prefer `const` constructors in widgets
+- Use `const` for default parameter values
+- Enable `prefer_const_declarations` lint

package/skills/flutter-skills/rules/dart-spread-operator.md

@@ -0,0 +1,90 @@
+---
+title: Use Spread Operator for Collection Merging
+impact: LOW-MEDIUM
+impactDescription: More efficient collection operations
+tags: dart, spread, collections, merge
+---
+
+## Use Spread Operator for Collection Merging
+
+Use the spread operator (`...`) for efficient collection merging instead of addAll or concatenation.
+
+**Incorrect (multiple operations):**
+
+```dart
+List<int> combineNumbers() {
+  var result = <int>[];
+  result.addAll([1, 2, 3]);
+  result.add(4);
+  result.addAll([5, 6, 7]);
+  return result;
+}
+
+// Or inefficient concatenation
+List<int> combineNumbers() {
+  return [1, 2, 3] + [4] + [5, 6, 7]; // Creates intermediate lists
+}
+```
+
+**Correct (spread operator):**
+
+```dart
+List<int> combineNumbers() {
+  return [...[1, 2, 3], 4, ...[5, 6, 7]];
+}
+
+// Or more readable:
+List<int> combineNumbers() {
+  const first = [1, 2, 3];
+  const last = [5, 6, 7];
+  return [...first, 4, ...last];
+}
+```
+
+**Null-aware spread:**
+
+```dart
+List<Widget> buildWidgets(List<Widget>? extraWidgets) {
+  return [
+    const Header(),
+    ...?extraWidgets, // Only spreads if not null
+    const Footer(),
+  ];
+}
+```
+
+**With maps:**
+
+```dart
+Map<String, dynamic> mergeConfig(Map<String, dynamic> overrides) {
+  return {
+    'theme': 'dark',
+    'fontSize': 14,
+    ...overrides, // Overrides default values
+  };
+}
+```
+
+**In widget builders:**
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return Row(
+    children: [
+      const LeadingIcon(),
+      ...items.map((item) => ItemWidget(item: item)),
+      if (showTrailing) ...[
+        const Spacer(),
+        const TrailingIcon(),
+      ],
+    ],
+  );
+}
+```
+
+Benefits:
+- Single list creation
+- More readable
+- Works with const
+- Null-safety with `...?`

package/skills/flutter-skills/rules/dart-string-buffer.md

@@ -0,0 +1,77 @@
+---
+title: Use StringBuffer for String Concatenation
+impact: LOW-MEDIUM
+impactDescription: O(n) vs O(n²) for large strings
+tags: dart, string, buffer, performance
+---
+
+## Use StringBuffer for String Concatenation
+
+Use `StringBuffer` for building strings in loops to avoid O(n²) performance.
+
+**Incorrect (quadratic time complexity):**
+
+```dart
+String buildHtml(List<Item> items) {
+  var html = '<ul>';
+  for (final item in items) {
+    html += '<li>${item.name}</li>'; // Creates new string each iteration!
+  }
+  html += '</ul>';
+  return html;
+}
+// For 1000 items: ~500,000 character copies
+```
+
+**Correct (linear time complexity):**
+
+```dart
+String buildHtml(List<Item> items) {
+  final buffer = StringBuffer('<ul>');
+  for (final item in items) {
+    buffer.write('<li>${item.name}</li>'); // Efficient append
+  }
+  buffer.write('</ul>');
+  return buffer.toString();
+}
+// For 1000 items: ~10,000 character copies
+```
+
+**Common patterns:**
+
+```dart
+// Building log messages
+String formatLog(List<LogEntry> entries) {
+  final buffer = StringBuffer();
+  for (final entry in entries) {
+    buffer
+      ..write('[${entry.timestamp}] ')
+      ..write(entry.level.name.toUpperCase())
+      ..write(': ')
+      ..writeln(entry.message);
+  }
+  return buffer.toString();
+}
+
+// With writeAll for simple cases
+String joinItems(List<String> items) {
+  final buffer = StringBuffer();
+  buffer.writeAll(items, ', '); // Adds separator
+  return buffer.toString();
+}
+```
+
+**When += is fine:**
+- Fixed number of concatenations (not in loop)
+- Small strings
+- Readability matters more than performance
+
+```dart
+// This is fine - constant number of operations
+final message = 'Hello, ' + name + '! Welcome to ' + appName + '.';
+
+// Or use interpolation (preferred)
+final message = 'Hello, $name! Welcome to $appName.';
+```
+
+Rule of thumb: Use StringBuffer when concatenating in loops or building strings from many parts.

package/skills/flutter-skills/rules/layout-avoid-opacity.md

@@ -0,0 +1,110 @@
+---
+title: Use AnimatedOpacity Instead of Opacity
+impact: MEDIUM
+impactDescription: Smoother animations, less jank
+tags: layout, opacity, animation, performance
+---
+
+## Use AnimatedOpacity Instead of Opacity
+
+Use `AnimatedOpacity` or `FadeTransition` instead of `Opacity` widget for animated opacity changes.
+
+**Incorrect (causes unnecessary repaints):**
+
+```dart
+class BadFade extends StatefulWidget {
+  @override
+  State<BadFade> createState() => _BadFadeState();
+}
+
+class _BadFadeState extends State<BadFade> {
+  double _opacity = 1.0;
+
+  @override
+  Widget build(BuildContext context) {
+    return Opacity(
+      opacity: _opacity,
+      child: ExpensiveWidget(),
+    );
+  }
+  
+  void fadeOut() {
+    // Each setState causes full rebuild
+    for (var i = 10; i >= 0; i--) {
+      Future.delayed(Duration(milliseconds: i * 50), () {
+        setState(() => _opacity = i / 10);
+      });
+    }
+  }
+}
+```
+
+**Correct (AnimatedOpacity handles transitions):**
+
+```dart
+class GoodFade extends StatefulWidget {
+  const GoodFade({super.key});
+
+  @override
+  State<GoodFade> createState() => _GoodFadeState();
+}
+
+class _GoodFadeState extends State<GoodFade> {
+  bool _visible = true;
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedOpacity(
+      opacity: _visible ? 1.0 : 0.0,
+      duration: const Duration(milliseconds: 300),
+      child: const ExpensiveWidget(), // Only built once
+    );
+  }
+  
+  void toggleVisibility() {
+    setState(() => _visible = !_visible);
+    // Animation handled internally without extra rebuilds
+  }
+}
+```
+
+**With FadeTransition for controller-based animations:**
+
+```dart
+class FadeWidget extends StatefulWidget {
+  const FadeWidget({super.key});
+
+  @override
+  State<FadeWidget> createState() => _FadeWidgetState();
+}
+
+class _FadeWidgetState extends State<FadeWidget>
+    with SingleTickerProviderStateMixin {
+  late final AnimationController _controller;
+  late final Animation<double> _opacity;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = AnimationController(
+      duration: const Duration(milliseconds: 300),
+      vsync: this,
+    );
+    _opacity = CurvedAnimation(parent: _controller, curve: Curves.easeIn);
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return FadeTransition(
+      opacity: _opacity,
+      child: const ExpensiveWidget(),
+    );
+  }
+}
+```

package/skills/flutter-skills/rules/layout-clip-behavior.md

@@ -0,0 +1,94 @@
+---
+title: Set clipBehavior.none When Not Needed
+impact: MEDIUM
+impactDescription: Reduces GPU overdraw
+tags: layout, clip, performance, rendering
+---
+
+## Set clipBehavior.none When Not Needed
+
+Disable clipping on containers and stacks when content doesn't overflow.
+
+**Incorrect (unnecessary clipping):**
+
+```dart
+class BadLayout extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      // Default clipBehavior may clip unnecessarily
+      decoration: BoxDecoration(
+        color: Colors.white,
+        borderRadius: BorderRadius.circular(8),
+      ),
+      child: Row(
+        children: [
+          Icon(Icons.star),
+          Text('Rating'),
+        ],
+      ),
+    );
+  }
+}
+```
+
+**Correct (explicit no clipping):**
+
+```dart
+class GoodLayout extends StatelessWidget {
+  const GoodLayout({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      clipBehavior: Clip.none, // Explicit - no clipping needed
+      decoration: BoxDecoration(
+        color: Colors.white,
+        borderRadius: BorderRadius.circular(8),
+      ),
+      child: const Row(
+        children: [
+          Icon(Icons.star),
+          Text('Rating'),
+        ],
+      ),
+    );
+  }
+}
+```
+
+**Stack with overflow:**
+
+```dart
+// When children intentionally overflow
+Stack(
+  clipBehavior: Clip.none, // Allow overflow
+  children: [
+    Container(width: 100, height: 100, color: Colors.blue),
+    Positioned(
+      top: -20, // Overflows parent - needs Clip.none
+      child: Icon(Icons.star),
+    ),
+  ],
+)
+```
+
+**Clip options:**
+
+```dart
+// Clip.none - No clipping, best performance
+// Clip.hardEdge - Fastest clipping if needed
+// Clip.antiAlias - Smooth edges, slower
+// Clip.antiAliasWithSaveLayer - Smoothest, slowest
+
+// For rounded containers that need clipping:
+Container(
+  clipBehavior: Clip.hardEdge, // Use simplest clip that works
+  decoration: BoxDecoration(
+    borderRadius: BorderRadius.circular(8),
+  ),
+  child: Image.network(url), // Image must be clipped
+)
+```
+
+Use `Clip.none` as default, only enable clipping when content overflows.