openskill-ai 1.0.0

package/skills/flutter-skills/rules/animation-cached-images.md

@@ -0,0 +1,112 @@
+---
+title: Cache Animation Frames When Possible
+impact: MEDIUM
+impactDescription: Reduces per-frame computation
+tags: animation, cache, frames, performance
+---
+
+## Cache Animation Frames When Possible
+
+For complex animations that repeat, consider caching rendered frames or using simpler representations during motion.
+
+**Incorrect (complex rendering every frame):**
+
+```dart
+class BadComplexAnim extends StatefulWidget {
+  @override
+  State<BadComplexAnim> createState() => _BadComplexAnimState();
+}
+
+class _BadComplexAnimState extends State<BadComplexAnim>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedBuilder(
+      animation: _controller,
+      builder: (context, _) {
+        // Complex widget rebuilt 60 times per second
+        return Transform.rotate(
+          angle: _controller.value * 2 * pi,
+          child: ComplexShadowedWidget(), // Expensive!
+        );
+      },
+    );
+  }
+}
+```
+
+**Correct (cache animated content in layer):**
+
+```dart
+class GoodComplexAnim extends StatefulWidget {
+  const GoodComplexAnim({super.key});
+
+  @override
+  State<GoodComplexAnim> createState() => _GoodComplexAnimState();
+}
+
+class _GoodComplexAnimState extends State<GoodComplexAnim>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+
+  @override
+  Widget build(BuildContext context) {
+    return AnimatedBuilder(
+      animation: _controller,
+      // Child is built ONCE and cached
+      child: const RepaintBoundary(
+        child: ComplexShadowedWidget(),
+      ),
+      builder: (context, child) {
+        // Only transform is applied per-frame
+        return Transform.rotate(
+          angle: _controller.value * 2 * pi,
+          child: child, // Reused cached child
+        );
+      },
+    );
+  }
+}
+```
+
+**For repeated sprite animations:**
+
+```dart
+class SpriteAnimation extends StatelessWidget {
+  final List<ui.Image> frames; // Pre-rendered frames
+  final int currentFrame;
+  
+  const SpriteAnimation({
+    super.key,
+    required this.frames,
+    required this.currentFrame,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return CustomPaint(
+      painter: SpritePainter(frames[currentFrame]),
+    );
+  }
+}
+
+class SpritePainter extends CustomPainter {
+  final ui.Image frame;
+  SpritePainter(this.frame);
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    canvas.drawImage(frame, Offset.zero, Paint());
+  }
+
+  @override
+  bool shouldRepaint(SpritePainter old) => frame != old.frame;
+}
+```
+
+**When to cache:**
+- Rotating complex widgets with shadows
+- Scaling elaborate UI
+- Looping animations with static content

package/skills/flutter-skills/rules/animation-physics.md

@@ -0,0 +1,105 @@
+---
+title: Use Physics-Based Animations
+impact: MEDIUM
+impactDescription: More natural, interruptible animations
+tags: animation, physics, spring, fling
+---
+
+## Use Physics-Based Animations
+
+Use physics-based animations for natural feeling interactions that can be interrupted and redirected.
+
+**Incorrect (fixed duration feels artificial):**
+
+```dart
+class BadDrag extends StatefulWidget {
+  @override
+  State<BadDrag> createState() => _BadDragState();
+}
+
+class _BadDragState extends State<BadDrag>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+  double _offset = 0;
+
+  void _onDragEnd(DragEndDetails details) {
+    // Fixed duration regardless of velocity - unnatural
+    _controller.animateTo(
+      0,
+      duration: const Duration(milliseconds: 300),
+    );
+  }
+}
+```
+
+**Correct (physics-based spring):**
+
+```dart
+class GoodDrag extends StatefulWidget {
+  const GoodDrag({super.key});
+
+  @override
+  State<GoodDrag> createState() => _GoodDragState();
+}
+
+class _GoodDragState extends State<GoodDrag>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+  
+  void _onDragEnd(DragEndDetails details) {
+    // Spring simulation - natural bounce back
+    final simulation = SpringSimulation(
+      SpringDescription(
+        mass: 1,
+        stiffness: 500,
+        damping: 25,
+      ),
+      _controller.value, // Current position
+      0, // Target position
+      details.velocity.pixelsPerSecond.dx / 1000, // Initial velocity
+    );
+    
+    _controller.animateWith(simulation);
+  }
+}
+```
+
+**Fling animation for scrolling:**
+
+```dart
+void _onPanEnd(DragEndDetails details) {
+  final velocity = details.velocity.pixelsPerSecond.dx;
+  
+  final simulation = FrictionSimulation(
+    0.135, // Friction coefficient
+    _position,
+    velocity,
+  );
+  
+  _controller.animateWith(simulation);
+}
+```
+
+**Built-in spring curves:**
+
+```dart
+// Use Curves.elasticOut for spring-like effect
+AnimatedContainer(
+  duration: const Duration(milliseconds: 500),
+  curve: Curves.elasticOut, // Spring overshoot
+  transform: Matrix4.translationValues(_offset, 0, 0),
+  child: content,
+)
+
+// Or SpringCurve for more control
+const spring = SpringDescription(
+  mass: 1,
+  stiffness: 100,
+  damping: 10,
+);
+```
+
+Physics animations feel more natural because:
+- Duration depends on distance and velocity
+- Can be interrupted mid-animation
+- Respect user gesture momentum

package/skills/flutter-skills/rules/animation-reduce-overdraw.md

@@ -0,0 +1,111 @@
+---
+title: Minimize Overdraw in Animations
+impact: MEDIUM
+impactDescription: Reduces GPU workload
+tags: animation, overdraw, gpu, performance
+---
+
+## Minimize Overdraw in Animations
+
+Reduce overlapping painted areas during animations to decrease GPU workload.
+
+**Incorrect (multiple overlapping layers):**
+
+```dart
+class BadOverdraw extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Stack(
+      children: [
+        // Background painted everywhere
+        Container(color: Colors.blue),
+        // Card overlaps background
+        Center(
+          child: Container(
+            width: 200,
+            height: 200,
+            decoration: BoxDecoration(
+              color: Colors.white,
+              boxShadow: [
+                BoxShadow(
+                  blurRadius: 20,
+                  color: Colors.black26,
+                ),
+              ],
+            ),
+            // Icon overlaps card
+            child: Icon(Icons.star, size: 100, color: Colors.yellow),
+          ),
+        ),
+      ],
+    );
+  }
+}
+```
+
+**Correct (minimize overlap):**
+
+```dart
+class GoodOverdraw extends StatelessWidget {
+  const GoodOverdraw({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return ColoredBox(
+      color: Colors.blue,
+      child: Center(
+        child: PhysicalModel(
+          color: Colors.white,
+          elevation: 8, // Uses GPU shadow, more efficient
+          borderRadius: BorderRadius.circular(8),
+          child: const SizedBox(
+            width: 200,
+            height: 200,
+            child: Icon(Icons.star, size: 100, color: Colors.yellow),
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+**Debug overdraw:**
+
+```dart
+void main() {
+  // Shows overdraw with colors
+  // Green = 1x, Light green = 2x, Yellow = 3x, Red = 4x+
+  debugPaintLayerBordersEnabled = true;
+  runApp(MyApp());
+}
+
+// Or use DevTools Performance Overlay
+MaterialApp(
+  showPerformanceOverlay: true,
+  home: MyHomePage(),
+)
+```
+
+**Tips to reduce overdraw:**
+- Use `ColoredBox` instead of `Container(color: ...)`
+- Use `PhysicalModel` for shadows instead of `BoxShadow`
+- Avoid stacking opaque widgets
+- Use `saveLayer` sparingly (opacity, clips with antialiasing)
+- Prefer solid backgrounds over gradients where possible
+
+**For animated opacity:**
+
+```dart
+// Bad - saveLayer on every frame
+Opacity(
+  opacity: animation.value,
+  child: ComplexWidget(),
+)
+
+// Better - use FadeTransition
+FadeTransition(
+  opacity: animation,
+  child: const ComplexWidget(),
+)
+```

package/skills/flutter-skills/rules/animation-tween-sequence.md

@@ -0,0 +1,112 @@
+---
+title: Use TweenSequence for Complex Animations
+impact: MEDIUM
+impactDescription: Cleaner multi-phase animations
+tags: animation, tween, sequence, multi-step
+---
+
+## Use TweenSequence for Complex Animations
+
+Use `TweenSequence` for multi-phase animations instead of chaining or complex state logic.
+
+**Incorrect (manual phase management):**
+
+```dart
+class BadMultiPhase extends StatefulWidget {
+  @override
+  State<BadMultiPhase> createState() => _BadMultiPhaseState();
+}
+
+class _BadMultiPhaseState extends State<BadMultiPhase>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+  int _phase = 0;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = AnimationController(
+      duration: const Duration(seconds: 1),
+      vsync: this,
+    )..addStatusListener((status) {
+        if (status == AnimationStatus.completed) {
+          _phase++;
+          if (_phase < 3) _controller.forward(from: 0);
+        }
+      });
+  }
+
+  double get _scale {
+    switch (_phase) {
+      case 0: return 1.0 + _controller.value * 0.5; // 1.0 -> 1.5
+      case 1: return 1.5 - _controller.value * 0.3; // 1.5 -> 1.2
+      case 2: return 1.2 - _controller.value * 0.2; // 1.2 -> 1.0
+      default: return 1.0;
+    }
+  }
+}
+```
+
+**Correct (TweenSequence):**
+
+```dart
+class GoodMultiPhase extends StatefulWidget {
+  const GoodMultiPhase({super.key});
+
+  @override
+  State<GoodMultiPhase> createState() => _GoodMultiPhaseState();
+}
+
+class _GoodMultiPhaseState extends State<GoodMultiPhase>
+    with SingleTickerProviderStateMixin {
+  late AnimationController _controller;
+  late Animation<double> _scaleAnimation;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = AnimationController(
+      duration: const Duration(seconds: 3),
+      vsync: this,
+    );
+
+    _scaleAnimation = TweenSequence<double>([
+      TweenSequenceItem(
+        tween: Tween(begin: 1.0, end: 1.5)
+            .chain(CurveTween(curve: Curves.easeOut)),
+        weight: 33,
+      ),
+      TweenSequenceItem(
+        tween: Tween(begin: 1.5, end: 1.2)
+            .chain(CurveTween(curve: Curves.easeInOut)),
+        weight: 33,
+      ),
+      TweenSequenceItem(
+        tween: Tween(begin: 1.2, end: 1.0)
+            .chain(CurveTween(curve: Curves.easeIn)),
+        weight: 34,
+      ),
+    ]).animate(_controller);
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return ScaleTransition(
+      scale: _scaleAnimation,
+      child: const Icon(Icons.favorite, size: 50),
+    );
+  }
+}
+```
+
+**Benefits:**
+- Single animation controller
+- Declarative phase definitions
+- Each phase can have its own curve
+- Weight controls relative duration

package/skills/flutter-skills/rules/async-cancel-subscriptions.md

@@ -0,0 +1,112 @@
+---
+title: Cancel Stream Subscriptions on Dispose
+impact: HIGH
+impactDescription: Prevents memory leaks and errors
+tags: async, streams, dispose, memory
+---
+
+## Cancel Stream Subscriptions on Dispose
+
+Always cancel stream subscriptions in `dispose()` to prevent memory leaks and errors from updates to disposed widgets.
+
+**Incorrect (subscription never cancelled):**
+
+```dart
+class BadStreamWidget extends StatefulWidget {
+  @override
+  State<BadStreamWidget> createState() => _BadStreamWidgetState();
+}
+
+class _BadStreamWidgetState extends State<BadStreamWidget> {
+  String data = '';
+
+  @override
+  void initState() {
+    super.initState();
+    // This subscription will leak!
+    myStream.listen((value) {
+      setState(() => data = value);
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) => Text(data);
+}
+```
+
+**Correct (subscription cancelled on dispose):**
+
+```dart
+class GoodStreamWidget extends StatefulWidget {
+  const GoodStreamWidget({super.key});
+
+  @override
+  State<GoodStreamWidget> createState() => _GoodStreamWidgetState();
+}
+
+class _GoodStreamWidgetState extends State<GoodStreamWidget> {
+  String data = '';
+  StreamSubscription<String>? _subscription;
+
+  @override
+  void initState() {
+    super.initState();
+    _subscription = myStream.listen((value) {
+      setState(() => data = value);
+    });
+  }
+
+  @override
+  void dispose() {
+    _subscription?.cancel(); // Critical!
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) => Text(data);
+}
+```
+
+**Or use StreamBuilder (handles subscription automatically):**
+
+```dart
+class BetterStreamWidget extends StatelessWidget {
+  const BetterStreamWidget({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return StreamBuilder<String>(
+      stream: myStream,
+      builder: (context, snapshot) {
+        if (snapshot.hasData) {
+          return Text(snapshot.data!);
+        }
+        return const CircularProgressIndicator();
+      },
+    );
+  }
+}
+```
+
+**Multiple subscriptions pattern:**
+
+```dart
+class _MultiStreamState extends State<MultiStreamWidget> {
+  final List<StreamSubscription> _subscriptions = [];
+
+  @override
+  void initState() {
+    super.initState();
+    _subscriptions.add(stream1.listen((_) {}));
+    _subscriptions.add(stream2.listen((_) {}));
+  }
+
+  @override
+  void dispose() {
+    for (final sub in _subscriptions) {
+      sub.cancel();
+    }
+    super.dispose();
+  }
+}
+```

package/skills/flutter-skills/rules/async-compute.md

@@ -0,0 +1,78 @@
+---
+title: Use compute() for Heavy Synchronous Work
+impact: HIGH
+impactDescription: Prevents UI jank
+tags: async, compute, isolate, performance
+---
+
+## Use compute() for Heavy Synchronous Work
+
+Offload CPU-intensive synchronous work to an isolate using `compute()` to prevent UI jank.
+
+**Incorrect (blocks UI thread):**
+
+```dart
+class BadJsonParser extends StatelessWidget {
+  Future<void> parseData() async {
+    final response = await http.get(Uri.parse('api/data'));
+    
+    // This blocks the UI thread!
+    final parsed = jsonDecode(response.body);
+    final processed = heavyProcessing(parsed);
+  }
+}
+```
+
+**Correct (offload to isolate):**
+
+```dart
+class GoodJsonParser extends StatelessWidget {
+  const GoodJsonParser({super.key});
+
+  // Must be top-level or static function
+  static Map<String, dynamic> parseJson(String json) {
+    final parsed = jsonDecode(json);
+    return heavyProcessing(parsed);
+  }
+
+  Future<Map<String, dynamic>> parseData() async {
+    final response = await http.get(Uri.parse('api/data'));
+    
+    // Runs in separate isolate, UI stays responsive
+    return compute(parseJson, response.body);
+  }
+}
+```
+
+**For multiple heavy operations:**
+
+```dart
+Future<ProcessedData> processAll(RawData raw) async {
+  // Run heavy computations in parallel on separate isolates
+  final results = await Future.wait([
+    compute(parseImages, raw.images),
+    compute(parseVideos, raw.videos),
+    compute(parseDocuments, raw.documents),
+  ]);
+  
+  return ProcessedData(
+    images: results[0],
+    videos: results[1],
+    documents: results[2],
+  );
+}
+```
+
+**When to use compute():**
+- JSON parsing of large payloads (>100KB)
+- Image processing or compression
+- Cryptographic operations
+- Complex data transformations
+- Any operation taking >16ms
+
+**Limitations:**
+- Function must be top-level or static
+- Arguments must be serializable (no closures)
+- Has isolate spawn overhead (~5-20ms)
+
+For very frequent operations, consider using `Isolate.spawn` with ports for persistent workers.