SUMMARY

Enable packages to directly expose documentation, prompts, or other features to AI Agents

Author: Jake MacDonald (@jakemac53)

Go Link: flutter.dev/go/packaged-ai-assets
Prototype: https://github.com/dart-lang/ai/tree/packaged-ai-assets-prototype

Created: 1/2026   /  Last updated: 4/2026

Status: Implementation starting

WHAT PROBLEM IS THIS SOLVING?

With the growing popularity of AI coding agents, it is only natural that package authors will want to improve the performance of their packages in these agents, by exposing relevant information, guides, custom commands, etc to those agents.

Today, this requires shipping something separate from the actual package, whether that be an MCP server, extension, or just a repo of prompts/skills. This requires manual work for your users and also has a discoverability barrier to adoption. Additionally, many of the emerging tools in this space require node/npx which should not be a requirement for Dart/Flutter development.

The objective of this document is to provide a way for package authors to automatically include these resources, via the Dart/Flutter MCP server.  This way, there is only one tool to install, and any time you add a new package or update a package, all the relevant Agent related features will be up to date.

BACKGROUND

Audience

Package authors and users of AI coding Agents.

Glossary

• MCP - The Model Context Protocol connects agents to information/tools.
• Dart/Flutter MCP Server - The MCP server for Dart/Flutter development.
• Skills - Conditionally included tools/prompts for agents.
• Resources - Text or other content provided by an MCP server to an Agent.
• Prompts - Custom workflows provided by an MCP server to an Agent (user invoked usually).
• Tools - Functions exposed by an MCP server to an Agent (agent invoked).

OVERVIEW

At a high level, the proposal is to provide a configuration file following the package:extension_discovery format, at extension/mcp/config.yaml which describes all the AI Agent related resources provided by the package. The Dart/Flutter MCP server will read these files from your immediate dependencies, and surface the resources directly to your AI Agent.

Non-goals

• Skills support: Note that resources/prompts are very similar to skills, and the main difference is the user interaction model as implemented by clients (are they auto included by the model or explicitly included by the user?). The MCP standard is looking at adding skills as well. For now, we want to remain in a holding pattern here, and stay coupled to the MCP specification and features it currently supports.

• Some clients already implement automatic inclusion of MCP resources into the context, which gives you most of what skills gives you.
• We could add a `list_package_skills`  tool, as a stopgap measure here if desired. This would ensure all agents have the ability to list skills and include them, but the skills would still not be pre-emptively included, and it is hard to reliably get clients to list skills before proceeding with tasks.
• See also the “skills over mcp” working group meetings.

• Tools support: While we may look at this in the future, you can easily just add Dart scripts under the bin/ dir, and then a prompt to execute dart run <package>:<script>. This would also ensure we don’t get tool bloat in the MCP server, and long term this probably is still the right choice.

USAGE EXAMPLES

Package authors:

Consider the flutter package itself as an example, we could ship a structure like the following in the flutter repo:

packages/
.. flutter/

.... extension/
...... mcp/

........ config.yaml
........ resources/
.......... slivers/
............ really_awesome_doc_on_slivers.md
........ prompts/

.......... widgets/

............ split_up_into_subwidgets.md

config.yaml:

resources:

  # A custom resource just for agents
 - name: slivers_tutorial # Defaults to the basename of the path

    title: "Slivers Tutorial"

    description: "Become a slivers expert with this doc!"

    path: resources/slivers/really_awesome_doc_on_slivers.md

  # A resource pointing to an existing example
 - title: "Using a ListBuilder for an infinite scrolling list"

    description: "End to end example of implementing an infinite scrolling list with a ListBuilder"

    path: ../../example/list_builder_example.dart

prompts:

  - name: split_into_subwidgets # Defaults to the basename of the path

    title: "Split into subwidgets"

    description: "Splits a widget up into multiple widgets"

    path: prompts/widgets/split_up_into_subwidgets.md

Package Consumers:

A consumer of the flutter package connects their agent to the Dart MCP Server, and the following things happen:

• @<resource> - Including resources using @ (with auto complete) is the industry standard. So for instance `@state` will automatically surface state related documentation from your dependencies.

• Some agents may also automatically choose to include these, similar to how skills work.
• The “resource” here could be a partial URI, or name, depending on how the clients handle resources.
• Resource names are automatically prefixed with the package name followed by a `/`.

• /<prompt-name> - Prompts are typically surfaced as "slash commands" in your chat, and also support auto complete, so /widget  would auto complete all the widget related slash commands as an example.

• By prefixing all names with the package name (the MCP server will do this), you can easily find all commands from a package by doing /<package-name>
  

DETAILED DESIGN/DISCUSSION

Resources

Resources are listed under the resources key of the config.yaml file.

Format:

This is a simple list of resource objects, matching the MCP Resource schema with the exception of a couple small differences:

• The uri field is replaced with a path field. This must be a relative path, which cannot escape the package root, and a file at that path must exist, containing the content of the resource. The path will be converted into a URI of the following form for the resource:

• package-root://<package-name>/<path/from/package/root>

• There is an additional field visibility which is described below.
• The name is optional and defaults to the basename of the file.

• The package name will be prefixed to this name followed by a forward slash, to avoid collisions.

Note: Providing the full package relative path in the URI allows resources to live anywhere in the package, so you can reference things under example/ , docs/, etc.

Alternative: We could just use the actual (file:) URI of the package root, but this would often be a pub cache path and we probably don’t want agents mucking about in there. This is also potentially more flexible for non-file based environments.

Prompts

Prompts are listed under the prompts key of the config.yaml file.

Format:

This is a simple list of prompt objects, matching the MCP Prompt schema, with a few small differences:

• An additional path field. This must be a relative path, which cannot escape the package root, and a file at that path must exist, containing the full prompt.
• There is an additional field visibility which is described below.
• The name is optional and defaults to the basename of the file.

• The package name will be prefixed to this name followed by a forward slash, to avoid collisions.

Prompt names will also be prefixed with the package name, when surfaced by the Dart MCP server.

Prompt arguments

MCP prompts support arguments, which all must be strings (repeated arguments are not supported by the MCP spec).

If any arguments are provided for a prompt, then the prompt file will be parsed as a mustache template using package:mustache_template, with the provided arguments.

Visibility

The visibility field defaults to public, but may be set to private. Additional visibility options may be added in the future.

Note that MCP features cannot be scoped to portions of a workspace, so private functionality will be exposed if the package is a part of any MCP root - which typically corresponds to the current working directory or all open directories in your editor.

All public features will be exposed to the current package as well as any package directly depending on this package.

ECOSYSTEM IMPACT AND RISKS

Package author overhead

It has been expressed by some package authors that they are concerned about the extra overhead supporting these features may incur above and beyond the normal duties of package maintenance.  There are several potential facets to this:

Users filing issues

As a core part of the ecosystem, users of packages may more aggressively file issues on these packages asking for AI support, beyond what they already do.

This could be highly distracting and annoying for package authors.

Mitigation: We should emphasize in our own documentation that this support is optional. Not all packages need this support if they are well established and LLMs understand them well. Or package authors may choose not to provide this support for any reason. We can also direct users towards releasing their own packages that can be paired with an existing package, but provide just the AI support for it.

Pub package scoring

An additional aspect that would feed into this is pub package scoring. If we were to penalize packages based on not providing these AI resources, then that would further push package authors to spend time on these resources, when they would rather not do so.

Mitigation: We will not penalize pub package scores for not having AI support files.

Using pub to ship non-Dart code

This proposal does explicitly enable, and even promote as a valid option, the shipping of packages which only provide AI support for Dart/Flutter development, and no Dart code.

There is some risk that pub could become swamped with LLM related packages of little value, which would then make it less useful as a whole.

Decision: While this concern is heard, the team (including representatives from the pub package manager) has decided that this is an appropriate use of pub. There is established precedent here as well with packages that only publish analysis_options.yaml files, which has worked out well. Pub already has scoring mechanisms and voting to address some of these concerns and these can be extended as needed.

Packages will need to publish any time they update these AI resources

Yes, it is true that any package containing AI resources will need to publish any time they want to release new versions of those resources.

The proposal does not allow pointing to external websites as a risk mitigation for prompt injection which would otherwise be one way of avoiding this.

Solution: This proposal allows for putting your AI assets in a separate package if that makes the most sense for your package. This may be an appropriate choice for some packages. In general though, changing these assets is not a breaking change, and authors should feel fine about releasing their package as often as they see fit.

Package bloat

Packages may become larger due to including these assets, whether as a result of the configuration file itself or any additional resources they point to.

These are generally just text files, and the bloat should be minimal. We already ship many more things with packages than just what is strictly needed to use the package - we ship everything in the package unless explicitly excluded. This includes any documentation, examples, tests, etc.

Decision: The risk here is minimal and not of concern. Packages do have a maximum size limit as well to mitigate this.

EDGE CASES

Multiple Package Configs

This is actually a fairly common case - people often have multiple packages open at once. In this case we will surface the resources and prompts from the latest version found in any open package.

This is a pragmatic solution that reduces duplication and ensures our URIs can be kept short. When choosing a version of a package to surface, the latest one is the obvious choice, but there will be edge cases where docs are incorrect when working on multiple packages with different versions of packages simultaneously.

Package Dependencies/Open Packages Change

Our data may become out of date whenever the set of package dependencies changes, or a new package is added to the current workspace.

For an initial release, we will not try to solve this problem. You will have to restart the MCP server after altering dependencies in order to get updated AI assistance features. Similarly editing your own features will require a restart of the server.

Many AI Agents will not respect the change notifications for MCP features anyways, so this would likely be wasted effort to implement at this time.

Future work

We may look for new package configs when new “roots” are added (adding a folder to your VsCode workspace as an example).

We will also may watch the package config files and config.yaml files that we did load for changes, and update the resources accordingly.

SECURITY

Prompt Injection

This proposal does potentially open up easier avenues for prompt injection, if a malicious or compromised package decides to do so. However, it is already possible for agents to read any files shipped with a package, so the risk is already there to some extent.

Ultimately, it is up to the MCP clients in this case to guard against malicious prompt injection. All MCP servers should be treated as untrusted already, similar to any content on the internet.

We will look into the best way to mitigate the security risk before proceeding, and determine if some action is necessary.

• We could choose to run some security scans on pub.dev during upload, to mitigate this risk. This should happen regardless of this proposal.

OPEN QUESTIONS

• When working on a project with one of these files, will they confuse the agent? By default the agent may see the original files in addition to the MCP resources/prompts. This could be resolved by hiding the extension/ dir from the agent.
•  Should we migrate all the flutter specific features from the gemini cli extension into packages/flutter/extensions/ai? Probably?
• Are there additional issues when dealing with projects that contain multiple packages, beyond what has been discussed?
• Should we enable surfacing things from transitive dependencies as well? We could add a transitive visibility option for this if desired. We do not plan this for V1 though.

TESTING PLAN

This can be unit and integration tested within the dart-lang/ai repo, where the MCP server is developed, using the same strategies as other features there.

DOCUMENTATION PLAN

We should add documentation to this to the pub package layout page, as well as the Dart MCP server page.

FUTURE WORK

• Add a skill for creating these files
• Investigate options for auto-inclusion of certain things like examples

OTHER OPTIONS CONSIDERED

Automatic docs generation

Instead of relying on specifically authored prompts/resources, we could try and automatically include certain resources/docs, such as examples.

We may still choose to do something like this in the future, but I view this is a distinctly different feature from what is proposed here, which are curated resources and prompts.

These files can also be auto generated if desired, so tooling can be built to automatically generate resources pointing to all your examples etc.

Shipping these resources through some other registry

In general the team feels that pub is the correct distribution mechanism here. The goal is to make things as easy as possible on both package authors and package consumers.

Having a separate registry or distribution mechanism which delivers the same value as this proposal would add more work for authors, make these resources less discoverable, and would likely just decrease usage.

It should also not be a requirement to install Node or any other tooling in order to use these features, which many of the alternatives would likely be based on.