Add AI Skills for Coding Assistants page and hint boxes

escamoteur · escamoteur · commit 5755437a9b36 · 2026-02-19T19:30:05.000-05:00
- New page: AI Skills for Coding Assistants (EN + ES)
- Added sidebar entry in both languages
- Added tip boxes on root index and all package getting-started pages (EN + ES)
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -162,6 +162,7 @@ export default defineConfig({
             collapsed: false,
             items: [
               { text: 'Artículos y Videos', link: '/es/misc/articles' },
+              { text: 'Skills de IA para Asistentes de Código', link: '/es/misc/ai_skills' },
               { text: 'How to contribute', link: '/misc/contribute' }
             ]
           }
@@ -319,6 +320,7 @@ export default defineConfig({
         collapsed: false,
         items: [
           { text: 'Articles & Videos', link: '/misc/articles.md' },
+          { text: 'AI Skills for Coding Assistants', link: '/misc/ai_skills.md' },
           { text: 'How to contribute', link: '/misc/contribute.md' }
         ]
       }
diff --git a/docs/documentation/command_it/getting_started.md b/docs/documentation/command_it/getting_started.md
@@ -7,6 +7,10 @@ command_it is a way to manage your state based on `ValueListenable` and the `Com
 
 ![command_it Data Flow](/images/command-it-flow.svg)
 
+::: tip AI-Assisted Development
+command_it ships with **AI skill files** in its `skills/` directory. They help AI tools generate correct command patterns. [Learn more →](/misc/ai_skills)
+:::
+
 ## Installation
 
 Add to your `pubspec.yaml`:
diff --git a/docs/documentation/get_it/getting_started.md b/docs/documentation/get_it/getting_started.md
@@ -35,6 +35,10 @@ next:
 
 ---
 
+::: tip AI-Assisted Development
+get_it ships with **AI skill files** in its `skills/` directory. They help AI coding assistants generate correct get_it code. [Learn more →](/misc/ai_skills)
+:::
+
 ## Installation
 
 Add get_it to your `pubspec.yaml`:
diff --git a/docs/documentation/listen_it/listen_it.md b/docs/documentation/listen_it/listen_it.md
@@ -24,6 +24,10 @@ These primitives work together to help you build reactive data flows in your Flu
 
 > Join our support Discord server: [https://discord.com/invite/Nn6GkYjzW](https://discord.com/invite/Nn6GkYjzW)
 
+::: tip AI-Assisted Development
+listen_it ships with **AI skill files** in its `skills/` directory. They help AI tools generate correct operator chains and collection patterns. [Learn more →](/misc/ai_skills)
+:::
+
 ## Installation
 
 Add to your `pubspec.yaml`:
diff --git a/docs/documentation/watch_it/getting_started.md b/docs/documentation/watch_it/getting_started.md
@@ -33,6 +33,10 @@ next:
 
 ---
 
+::: tip AI-Assisted Development
+watch_it ships with **AI skill files** in its `skills/` directory. They teach AI tools critical rules like watch ordering. [Learn more →](/misc/ai_skills)
+:::
+
 ## Installation
 
 Add watch_it to your `pubspec.yaml`:
diff --git a/docs/es/documentation/command_it/getting_started.md b/docs/es/documentation/command_it/getting_started.md
@@ -7,6 +7,10 @@ command_it es una forma de gestionar tu estado basada en `ValueListenable` y el
 
 ![Flujo de datos command_it](/images/command-it-flow.svg)
 
+::: tip Desarrollo Asistido por IA
+command_it incluye **archivos de skills de IA** en su directorio `skills/`. Ayudan a las herramientas de IA a generar patrones correctos de commands. [Más información →](/es/misc/ai_skills)
+:::
+
 ## Instalación
 
 Añade a tu `pubspec.yaml`:
diff --git a/docs/es/documentation/get_it/getting_started.md b/docs/es/documentation/get_it/getting_started.md
@@ -35,6 +35,10 @@ next:
 
 ---
 
+::: tip Desarrollo Asistido por IA
+get_it incluye **archivos de skills de IA** en su directorio `skills/`. Ayudan a los asistentes de código con IA a generar código correcto de get_it. [Más información →](/es/misc/ai_skills)
+:::
+
 ## Instalación
 
 Añade get_it a tu `pubspec.yaml`:
diff --git a/docs/es/documentation/listen_it/listen_it.md b/docs/es/documentation/listen_it/listen_it.md
@@ -24,6 +24,10 @@ Estas primitivas trabajan juntas para ayudarte a construir flujos de datos react
 
 > Únete a nuestro servidor de Discord para soporte: [https://discord.com/invite/Nn6GkYjzW](https://discord.com/invite/Nn6GkYjzW)
 
+::: tip Desarrollo Asistido por IA
+listen_it incluye **archivos de skills de IA** en su directorio `skills/`. Ayudan a las herramientas de IA a generar cadenas de operadores y patrones de colecciones correctos. [Más información →](/es/misc/ai_skills)
+:::
+
 ## Instalación
 
 Añade a tu `pubspec.yaml`:
diff --git a/docs/es/documentation/watch_it/getting_started.md b/docs/es/documentation/watch_it/getting_started.md
@@ -33,6 +33,10 @@ next:
 
 ---
 
+::: tip Desarrollo Asistido por IA
+watch_it incluye **archivos de skills de IA** en su directorio `skills/`. Enseñan a las herramientas de IA reglas críticas como el orden de los watch. [Más información →](/es/misc/ai_skills)
+:::
+
 ## Instalación
 
 Añade watch_it a tu `pubspec.yaml`:
diff --git a/docs/es/index.md b/docs/es/index.md
@@ -99,6 +99,10 @@ Operadores de transformación, filtrado, combinación y debounce para ValueNotif
 
 ---
 
+::: tip Desarrollo Asistido por IA
+Cada paquete de flutter_it incluye **archivos de skills de IA** que ayudan a Claude Code, Cursor, GitHub Copilot y otras herramientas de IA a generar código correcto. [Más información →](/es/misc/ai_skills)
+:::
+
 ## Primeros Pasos
 
 **¿Nuevo en flutter_it?** Empieza aquí:
diff --git a/docs/es/misc/ai_skills.md b/docs/es/misc/ai_skills.md
@@ -0,0 +1,95 @@
+---
+title: Skills de IA para Asistentes de Código
+---
+
+# Skills de IA para Asistentes de Código
+
+Cada paquete de flutter_it incluye **archivos de skills de IA** que ayudan a los asistentes de código con IA a generar código correcto e idiomático usando los paquetes.
+
+## ¿Qué son los Archivos de Skills de IA?
+
+Los archivos de skills de IA son archivos de conocimiento estructurado que enseñan a los asistentes de código con IA (como Claude Code, Cursor, GitHub Copilot y otros) cómo usar correctamente una librería. Contienen:
+
+- **Reglas críticas** que deben seguirse (ej. el requisito de orden de watch_it)
+- **Patrones comunes** con ejemplos de código completos
+- **Anti-patrones** con alternativas correctas
+- **Patrones de integración** entre paquetes
+- **Guía de arquitectura** para estructurar apps Flutter
+
+Los archivos de skills siguen el estándar abierto [Agent Skills](https://github.com/agentskills) — un formato basado en directorios con un archivo `SKILL.md` y frontmatter YAML que funciona con diferentes herramientas de IA.
+
+## ¿Qué Skills Incluye Cada Paquete?
+
+| Paquete | Skills Incluidos |
+|---------|-----------------|
+| **get_it** | `get-it-expert`, `flutter-architecture-expert` |
+| **watch_it** | `watch-it-expert`, `get-it-expert`, `flutter-architecture-expert`, `feed-datasource-expert` |
+| **command_it** | `command-it-expert`, `listen-it-expert`, `flutter-architecture-expert`, `feed-datasource-expert` |
+| **listen_it** | `listen-it-expert`, `flutter-architecture-expert` |
+
+Cada paquete incluye los skills más relevantes para su uso, así obtienes el contexto correcto sin importar con qué paquete comiences.
+
+## Los 7 Skills
+
+| Skill | Descripción |
+|-------|-------------|
+| `get-it-expert` | Registro del service locator, scopes, inicialización async, testing |
+| `watch-it-expert` | Widgets reactivos, funciones watch, handlers, ciclo de vida, reglas de orden |
+| `command-it-expert` | Patrón command, operaciones async, manejo de errores, restricciones |
+| `listen-it-expert` | Operadores de ValueListenable, colecciones reactivas, encadenamiento, transacciones |
+| `flutter-architecture-expert` | Arquitectura Flutter Pragmática (PFA) con Services/Managers/Views |
+| `feed-datasource-expert` | Feeds paginados, scroll infinito, ciclo de vida de proxies, conteo de referencias |
+
+## Cómo Usar con tu Herramienta de IA
+
+### Claude Code
+
+Los skills se **detectan automáticamente** del directorio `skills/` cuando abres un proyecto que contiene un paquete de flutter_it. No se necesita configuración adicional.
+
+También puedes copiar los skills a tu directorio global `~/.claude/skills/` para que estén disponibles en todos tus proyectos:
+
+```bash
+cp -r <paquete>/skills/* ~/.claude/skills/
+```
+
+### Cursor
+
+Copia el contenido relevante de `SKILL.md` a tu archivo `.cursorrules` en la raíz del proyecto:
+
+```bash
+cat <paquete>/skills/get-it-expert/SKILL.md >> .cursorrules
+```
+
+O referencia los archivos de skills en la configuración de Cursor.
+
+### GitHub Copilot
+
+Copia el contenido del skill a `.github/copilot-instructions.md`:
+
+```bash
+cat <paquete>/skills/get-it-expert/SKILL.md >> .github/copilot-instructions.md
+```
+
+### Otras Herramientas de IA
+
+Referencia los archivos `SKILL.md` directamente desde el directorio `skills/` de cada paquete. Los archivos son Markdown plano con frontmatter YAML y funcionan con cualquier herramienta que acepte archivos de contexto.
+
+## Archivos de Skills en GitHub
+
+Puedes explorar los archivos de skills directamente en cada repositorio:
+
+- [Skills de get_it](https://github.com/flutter-it/get_it/tree/master/skills)
+- [Skills de watch_it](https://github.com/flutter-it/watch_it/tree/main/skills)
+- [Skills de command_it](https://github.com/flutter-it/command_it/tree/main/skills)
+- [Skills de listen_it](https://github.com/flutter-it/listen_it/tree/main/skills)
+
+## Por Qué Esto Importa
+
+Los asistentes de código con IA son potentes, pero pueden generar patrones incorrectos sin el contexto adecuado. Por ejemplo:
+
+- Usar `isRunningSync` para actualizaciones de UI en lugar de `isRunning` (command_it)
+- Envolver llamadas watch en condicionales, rompiendo la regla de orden (watch_it)
+- Usar `copyWith` en DTOs en lugar de campos override en proxies (arquitectura)
+- Crear cadenas de operadores inline en `build()` sin caché (listen_it)
+
+Los archivos de skills previenen estos errores enseñando a la herramienta de IA los patrones correctos desde el inicio.
diff --git a/docs/index.md b/docs/index.md
@@ -99,6 +99,10 @@ Transform, filter, combine, and debounce operators for ValueNotifier—plus reac
 
 ---
 
+::: tip AI-Assisted Development
+Every flutter_it package ships with **AI skill files** that help Claude Code, Cursor, GitHub Copilot, and other AI tools generate correct code. [Learn more →](/misc/ai_skills)
+:::
+
 ## Getting Started
 
 **New to flutter_it?** Start here:
diff --git a/docs/misc/ai_skills.md b/docs/misc/ai_skills.md
@@ -0,0 +1,95 @@
+---
+title: AI Skills for Coding Assistants
+---
+
+# AI Skills for Coding Assistants
+
+Every flutter_it package ships with **AI skill files** that help AI coding assistants generate correct, idiomatic code using the packages.
+
+## What are AI Skill Files?
+
+AI skill files are structured knowledge files that teach AI coding assistants (like Claude Code, Cursor, GitHub Copilot, and others) how to properly use a library. They contain:
+
+- **Critical rules** that must be followed (e.g., watch_it's ordering requirement)
+- **Common patterns** with complete code examples
+- **Anti-patterns** with correct alternatives
+- **Integration patterns** between packages
+- **Architecture guidance** for structuring Flutter apps
+
+The skill files follow the [Agent Skills](https://github.com/agentskills) open standard — a directory-based format with a `SKILL.md` file and YAML frontmatter that works across different AI tools.
+
+## Which Skills Ship with Which Package?
+
+| Package | Skills Included |
+|---------|----------------|
+| **get_it** | `get-it-expert`, `flutter-architecture-expert` |
+| **watch_it** | `watch-it-expert`, `get-it-expert`, `flutter-architecture-expert`, `feed-datasource-expert` |
+| **command_it** | `command-it-expert`, `listen-it-expert`, `flutter-architecture-expert`, `feed-datasource-expert` |
+| **listen_it** | `listen-it-expert`, `flutter-architecture-expert` |
+
+Each package includes the skills most relevant to its usage, so you get the right context regardless of which package you start with.
+
+## All 7 Skills
+
+| Skill | Description |
+|-------|-------------|
+| `get-it-expert` | Service locator registration, scopes, async initialization, testing |
+| `watch-it-expert` | Reactive widgets, watch functions, handlers, lifecycle, ordering rules |
+| `command-it-expert` | Command pattern, async operations, error handling, restrictions |
+| `listen-it-expert` | ValueListenable operators, reactive collections, chaining, transactions |
+| `flutter-architecture-expert` | Pragmatic Flutter Architecture (PFA) with Services/Managers/Views |
+| `feed-datasource-expert` | Paginated feeds, infinite scroll, proxy lifecycle, reference counting |
+
+## How to Use with Your AI Tool
+
+### Claude Code
+
+Skills are **auto-detected** from the `skills/` directory when you open a project containing a flutter_it package. No extra setup needed.
+
+You can also copy the skills to your global `~/.claude/skills/` directory so they are available across all projects:
+
+```bash
+cp -r <package>/skills/* ~/.claude/skills/
+```
+
+### Cursor
+
+Copy the relevant `SKILL.md` content into your `.cursorrules` file at the project root:
+
+```bash
+cat <package>/skills/get-it-expert/SKILL.md >> .cursorrules
+```
+
+Or reference the skill files in your Cursor settings.
+
+### GitHub Copilot
+
+Copy the skill content to `.github/copilot-instructions.md`:
+
+```bash
+cat <package>/skills/get-it-expert/SKILL.md >> .github/copilot-instructions.md
+```
+
+### Other AI Tools
+
+Reference the `SKILL.md` files directly from the `skills/` directory of each package. The files are plain Markdown with YAML frontmatter and work with any tool that accepts context files.
+
+## Skill Files on GitHub
+
+You can browse the skill files directly in each package repository:
+
+- [get_it skills](https://github.com/flutter-it/get_it/tree/master/skills)
+- [watch_it skills](https://github.com/flutter-it/watch_it/tree/main/skills)
+- [command_it skills](https://github.com/flutter-it/command_it/tree/main/skills)
+- [listen_it skills](https://github.com/flutter-it/listen_it/tree/main/skills)
+
+## Why This Matters
+
+AI coding assistants are powerful, but they can generate incorrect patterns without proper context. For example:
+
+- Using `isRunningSync` for UI updates instead of `isRunning` (command_it)
+- Wrapping watch calls in conditionals, breaking the ordering rule (watch_it)
+- Using `copyWith` on DTOs instead of proxy override fields (architecture)
+- Creating operator chains inline in `build()` without caching (listen_it)
+
+The skill files prevent these mistakes by teaching the AI tool the correct patterns upfront.

Original file line number	Diff line number	Diff line change
`@@ -162,6 +162,7 @@ export default defineConfig({`
`162`	`162`	`collapsed: false,`
`163`	`163`	`items: [`
`164`	`164`	`{ text: 'Artículos y Videos', link: '/es/misc/articles' },`
	`165`	`+ { text: 'Skills de IA para Asistentes de Código', link: '/es/misc/ai_skills' },`
`165`	`166`	`{ text: 'How to contribute', link: '/misc/contribute' }`
`166`	`167`	`]`
`167`	`168`	`}`
`@@ -319,6 +320,7 @@ export default defineConfig({`
`319`	`320`	`collapsed: false,`
`320`	`321`	`items: [`
`321`	`322`	`{ text: 'Articles & Videos', link: '/misc/articles.md' },`
	`323`	`+ { text: 'AI Skills for Coding Assistants', link: '/misc/ai_skills.md' },`
`322`	`324`	`{ text: 'How to contribute', link: '/misc/contribute.md' }`
`323`	`325`	`]`
`324`	`326`	`}`