From 906bc14c2d4409e03fd66539563fbfecfbda2ba5 Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Thu, 3 Sep 2026 21:41:45 +0000 Subject: [PATCH 1/4] doc: point package skills to dart.dev canonical documentation --- sites/docs/firebase.json | 1 + sites/docs/src/content/ai/get-started.md | 4 +- sites/docs/src/content/ai/package-skills.md | 94 ------------------- sites/docs/src/content/ai/tools.md | 5 +- .../developing-packages.md | 3 +- .../packages-and-plugins/using-packages.md | 3 +- sites/docs/src/data/sidenav/default.yml | 2 +- 7 files changed, 11 insertions(+), 101 deletions(-) delete mode 100644 sites/docs/src/content/ai/package-skills.md diff --git a/sites/docs/firebase.json b/sites/docs/firebase.json index 1198ab9e8c..92a7766daf 100644 --- a/sites/docs/firebase.json +++ b/sites/docs/firebase.json @@ -19,6 +19,7 @@ { "regex": "(.*)\\.$", "destination": ":1", "type": 301 }, { "source": "/ads", "destination": "https://flutter.dev/monetization", "type": 301 }, + { "source": "/ai/package-skills", "destination": "https://dart.dev/ai/package-skills", "type": 301 }, { "source": "/blog", "destination": "https://flutter.dev/blog", "type": 301 }, { "source": "/blog/:rest*", "destination": "https://flutter.dev/blog/:rest*", "type": 301 }, { "source": "/community", "destination": "https://flutter.dev/community", "type": 301 }, diff --git a/sites/docs/src/content/ai/get-started.md b/sites/docs/src/content/ai/get-started.md index 0aa286dd9f..e84c31b65d 100644 --- a/sites/docs/src/content/ai/get-started.md +++ b/sites/docs/src/content/ai/get-started.md @@ -40,7 +40,7 @@ coding strategies and best practices. In addition to core Flutter plugins, you can also equip your assistant with skills that are shipped directly by third-party `pub.dev` -packages using the [skills](/ai/package-skills) package. +packages using the [skills](https://dart.dev/ai/package-skills) package. To learn more about the underlying architecture and capabilities of each tool, check out [How Flutter AI tools work](/ai/tools). @@ -288,7 +288,7 @@ npx skills add dart-lang/skills --skill '*' --agent universal --yes * To learn more about how skills and tools interact, check out [How Flutter AI tools work](/ai/tools). * To publish or consume skills from dependencies, refer to - [Package skills](/ai/package-skills). + [Package skills](https://dart.dev/ai/package-skills). * To give your assistant search access to official Flutter and Dart documentation, connect to the [Developer Knowledge MCP server]( https://developers.google.com/knowledge/mcp). diff --git a/sites/docs/src/content/ai/package-skills.md b/sites/docs/src/content/ai/package-skills.md deleted file mode 100644 index f0d0e9aa83..0000000000 --- a/sites/docs/src/content/ai/package-skills.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Package skills -description: >- - Learn how to bundle and consume agent skills in Dart and Flutter packages. ---- - -Package skills allow library authors to distribute AI instructions alongside -their code on [pub.dev](https://pub.dev). When developers add your package to -their project, their AI coding assistant can discover and use your package's -official skills. - -## For app developers: Consuming package skills - -When you add a package that includes skills, your coding assistant can access -expert guidance tailored specifically to that library's APIs, patterns, and -code generation workflows. - -### Discover and install skills from dependencies - -To scan your project dependencies and install available package skills, run: - -```bash -dart run skills@ get -``` - -The `skills` CLI scans your dependencies for bundled `skills/` directories, -presents the skills discovered, and lets you choose which skills to install. -Subsequent runs are incremental—displaying only new, updated, or removed -skills. - -To automatically install all discovered skills without interactive prompts, use -the `--all` flag: - -```bash -dart run skills@ get --all -``` - -### Install external skills - -You can also install standalone skills from external Git repositories using the -`add` command: - -```bash -dart run skills@ add https://github.com/my-org/custom-ai-skills.git -``` - ---- - -## For package authors: Publishing skills - -Package authors can publish skills directly in their `pub.dev` package -releases to teach AI assistants how to use their libraries correctly. - -### Add skills to your package repository - -1. Create a `skills/` directory in the root of your package repository. -2. Inside `skills/`, create a subdirectory prefixed with your package name (for - example, `skills/my-package-network/`). -3. Add a `SKILL.md` file containing YAML frontmatter (`name`, `description`) - and step-by-step markdown instructions. -4. Verify that the `skills/` directory is not excluded in your `.pubignore` - file. -5. Publish your package to `pub.dev`. - -### Example `SKILL.md` structure - -```markdown ---- -name: my_package-error-handling -description: >- - Use when making network requests with my_package to ensure safe patterns. ---- - -# Error handling guidelines - -## Best practices -* Always wrap network operations in a try/catch block. -* Catch `NetworkException` specifically to handle retries and diagnostics. -* Provide fallback UI state in the event of a timeout. - -## Example -1. Call `MyClient.fetchData()`. -2. Catch `NetworkException` and log `e.context`. -3. Return a fallback UI model. -``` - ---- - -## Next steps - -* To explore the underlying specification, check out - [agentskills.io](https://agentskills.io/). -* To file issues or give feedback on Dart skills tooling, visit the - [dart-lang/ai repository](https://github.com/dart-lang/ai). diff --git a/sites/docs/src/content/ai/tools.md b/sites/docs/src/content/ai/tools.md index 7d430fbf04..501d32b926 100644 --- a/sites/docs/src/content/ai/tools.md +++ b/sites/docs/src/content/ai/tools.md @@ -107,7 +107,7 @@ dart run skills@ get ``` To learn how to install or publish package skills, check out -[Package skills](/ai/package-skills). +[Package skills](https://dart.dev/ai/package-skills). --- @@ -174,4 +174,5 @@ interact: * Follow the [Get started with AI](/ai/get-started) guide to install official plugins in your editor. -* Learn how to consume and publish [Package skills](/ai/package-skills). +* Learn how to consume and publish + [Package skills](https://dart.dev/ai/package-skills). diff --git a/sites/docs/src/content/packages-and-plugins/developing-packages.md b/sites/docs/src/content/packages-and-plugins/developing-packages.md index 93af492a2d..60f183ae62 100644 --- a/sites/docs/src/content/packages-and-plugins/developing-packages.md +++ b/sites/docs/src/content/packages-and-plugins/developing-packages.md @@ -1079,6 +1079,7 @@ To distribute skills with your package: When developers add your package as a dependency, their assistants can automatically discover your instructions. To learn more about authoring -guidelines and best practices, check out [Package skills](/ai/package-skills). +guidelines and best practices, check out +[Ship skills with packages](https://dart.dev/tools/pub/package-skills). [Writing a good plugin]: {{site.flutter-blog}}/writing-a-good-flutter-plugin-1a561b986c9c diff --git a/sites/docs/src/content/packages-and-plugins/using-packages.md b/sites/docs/src/content/packages-and-plugins/using-packages.md index 622defeee2..c4d3d7ce14 100644 --- a/sites/docs/src/content/packages-and-plugins/using-packages.md +++ b/sites/docs/src/content/packages-and-plugins/using-packages.md @@ -514,4 +514,5 @@ dart run skills@ get ``` To learn more about how skills help coding assistants understand your -dependencies, check out [Package skills](/ai/package-skills). +dependencies, check out +[Package skills](https://dart.dev/ai/package-skills). diff --git a/sites/docs/src/data/sidenav/default.yml b/sites/docs/src/data/sidenav/default.yml index f3fc4564fe..e33b897585 100644 --- a/sites/docs/src/data/sidenav/default.yml +++ b/sites/docs/src/data/sidenav/default.yml @@ -652,7 +652,7 @@ - title: How AI tools work permalink: /ai/tools - title: Package skills - permalink: /ai/package-skills + permalink: https://dart.dev/ai/package-skills - title: Build AI-powered apps permalink: /ai/genui From d018dba255b6f436da66259cfc41f4dcde8907bb Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Thu, 3 Sep 2026 21:44:29 +0000 Subject: [PATCH 2/4] doc: point packages & plugins skills link to ship skills with packages --- sites/docs/src/data/sidenav/default.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites/docs/src/data/sidenav/default.yml b/sites/docs/src/data/sidenav/default.yml index e33b897585..9f359b1180 100644 --- a/sites/docs/src/data/sidenav/default.yml +++ b/sites/docs/src/data/sidenav/default.yml @@ -475,7 +475,7 @@ - title: Develop packages & plugins permalink: /packages-and-plugins/developing-packages - title: Package skills - permalink: /ai/package-skills + permalink: https://dart.dev/tools/pub/package-skills - title: Swift Package Manager permalink: /packages-and-plugins/swift-package-manager children: From 8ca0ba8ffeeca9539a1c319726ba3bb557219778 Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Thu, 3 Sep 2026 21:46:34 +0000 Subject: [PATCH 3/4] doc: update package skills references to distinguish consumer vs author guides --- sites/docs/src/content/ai/get-started.md | 4 +++- sites/docs/src/content/ai/tools.md | 8 ++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/sites/docs/src/content/ai/get-started.md b/sites/docs/src/content/ai/get-started.md index e84c31b65d..9fcbc0b9ab 100644 --- a/sites/docs/src/content/ai/get-started.md +++ b/sites/docs/src/content/ai/get-started.md @@ -287,8 +287,10 @@ npx skills add dart-lang/skills --skill '*' --agent universal --yes * To learn more about how skills and tools interact, check out [How Flutter AI tools work](/ai/tools). -* To publish or consume skills from dependencies, refer to +* To discover and install skills from dependencies, refer to [Package skills](https://dart.dev/ai/package-skills). +* To publish skills with your own packages, refer to + [Ship skills with packages](https://dart.dev/tools/pub/package-skills). * To give your assistant search access to official Flutter and Dart documentation, connect to the [Developer Knowledge MCP server]( https://developers.google.com/knowledge/mcp). diff --git a/sites/docs/src/content/ai/tools.md b/sites/docs/src/content/ai/tools.md index 501d32b926..75557fcc1c 100644 --- a/sites/docs/src/content/ai/tools.md +++ b/sites/docs/src/content/ai/tools.md @@ -106,8 +106,10 @@ skills using the `skills` CLI: dart run skills@ get ``` -To learn how to install or publish package skills, check out +To learn how to discover and install package skills, check out [Package skills](https://dart.dev/ai/package-skills). +To bundle skills with your own package, check out +[Ship skills with packages](https://dart.dev/tools/pub/package-skills). --- @@ -174,5 +176,7 @@ interact: * Follow the [Get started with AI](/ai/get-started) guide to install official plugins in your editor. -* Learn how to consume and publish +* Learn how to install skills with [Package skills](https://dart.dev/ai/package-skills). +* Learn how to distribute skills with + [Ship skills with packages](https://dart.dev/tools/pub/package-skills). From 56e1126ae029f3c267891c097add663c79482f43 Mon Sep 17 00:00:00 2001 From: Jess Kuras Date: Fri, 4 Sep 2026 19:20:11 +0000 Subject: [PATCH 4/4] doc: address review comments on package skills links --- sites/docs/src/content/ai/get-started.md | 2 +- sites/docs/src/data/sidenav/default.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sites/docs/src/content/ai/get-started.md b/sites/docs/src/content/ai/get-started.md index 9fcbc0b9ab..60a2522037 100644 --- a/sites/docs/src/content/ai/get-started.md +++ b/sites/docs/src/content/ai/get-started.md @@ -40,7 +40,7 @@ coding strategies and best practices. In addition to core Flutter plugins, you can also equip your assistant with skills that are shipped directly by third-party `pub.dev` -packages using the [skills](https://dart.dev/ai/package-skills) package. +packages using [package skills](https://dart.dev/ai/package-skills). To learn more about the underlying architecture and capabilities of each tool, check out [How Flutter AI tools work](/ai/tools). diff --git a/sites/docs/src/data/sidenav/default.yml b/sites/docs/src/data/sidenav/default.yml index 9f359b1180..870f87789a 100644 --- a/sites/docs/src/data/sidenav/default.yml +++ b/sites/docs/src/data/sidenav/default.yml @@ -474,7 +474,7 @@ permalink: /packages-and-plugins/dependency-management - title: Develop packages & plugins permalink: /packages-and-plugins/developing-packages - - title: Package skills + - title: Ship skills with packages permalink: https://dart.dev/tools/pub/package-skills - title: Swift Package Manager permalink: /packages-and-plugins/swift-package-manager