Package skills in Dart: giving AI agents the context to use a library

A library is already part of the project. Its documentation is available, its examples are public, and the source is open. An AI agent is asked to add a screen. The proposed implementation calls a method from an older release. Once that is corrected, the code compiles—but it still uses the library in a way that blurs responsibilities the project deliberately keeps separate.

The developer has to explain which example applies, what the package is responsible for, and why a pattern from another application does not fit this one. Some of those explanations will be needed again on the next task.

The problem is not necessarily an inability to read documentation. Knowing that information exists is different from having the relevant information available while making a particular decision. Source code explains what an implementation does. It does not always make the intended usage clear, especially when several technically valid approaches have different consequences.

Dart package skills let library authors distribute instructions for AI agents alongside their code. Developers can install those instructions into a project for use by a compatible agent tool. That introduces a practical question beyond the initial installation: what happens when the library's instructions change, but the team has already added rules of its own?

What a skill provides

A skill is a set of instructions for a particular kind of task. It typically describes when it applies, gives guidance and examples, and may refer to additional files. A package skill is distributed with a Dart package by its author.

It does not add a runtime feature to the application or retrain the model. It supplies material an agent can use. Whether and how that material is discovered and brought into a task depends on the agent tool. The Dart documentation describes installing package skills into directories used by supported tools.

The entry point is a file named SKILL.md. It begins with a name and a description of the tasks the skill is intended to help with, followed by Markdown instructions. A package author places these files in skill directories under the package's skills/ directory. The authoring guide explains the layout and naming requirements.

A small package might have this structure:

sample_package/
  pubspec.yaml
  lib/
  skills/
    sample-package-usage/
      SKILL.md
      references/
        examples.md

The value lies in the guidance, not the number of files. Several pages of generic advice about clean code are unlikely to help an agent choose the right way to use a specific API. A useful skill identifies the decision that needs to be made, explains the relevant constraints, and points to the details needed to implement it.

Why another document?

API documentation describes types, parameters, and method contracts. A tutorial walks a developer through a use case. A skill can direct an agent through the material relevant to its task: which section to consult, which constraints to check, and which example to follow.

That does not justify maintaining three independent descriptions of the same API. If an example is already maintained in the documentation, the skill can refer to it. Copying everything creates another version that can fall behind the implementation.

Some of the most useful guidance concerns decisions that a method signature cannot express. Consider an application that saves a form, updates the screen, and displays a notification. The screen state describes what should be visible now. The operation result describes how the save finished. The notification requires a UI action. Code can be well-typed while still confusing those responsibilities.

Libraries that separate them provide a good example of what a skill could explain. ark_mvp, part of ArkTelos, separates presentation state from transient UI actions. Those actions are represented by ViewEffect and delivered without storage or replay. Information that must remain available when a screen opens again therefore cannot exist only in an effect.

A useful instruction would explain how to make that choice: establish whether the information must survive the absence of the screen before choosing how to deliver it. Listing the methods that emit effects would not be enough.

This is an example of potential skill content, not an announcement of a released ark_mvp skill. The experiment below does not use ark_mvp. It examines how instruction files are managed, independently of the architectural advice they might contain.

The skills tool and the instructions it installs

Dart has a separate command-line package, skills, for managing these instructions. The naming is easy to confuse: skills are the materials; the skills package provides the tool that installs and maintains them.

Running pub get resolves application dependencies. It does not, by itself, mean that their instructions have been installed for an agent. The documentation shows a separate command for that step:

dart run skills@ get

This command installs and updates instructions in the current project. It is not a read-only listing operation. A separate project is a sensible place to try it, particularly before using bulk updates in a workspace containing local instructions that matter to the team.

The experiment used skills 1.0.1, pinned in a separate Dart runner package with a saved pubspec.lock, which records resolved dependency versions. The short command above does not reproduce that version pinning on its own.

The selected adapter was generic, which installed the skill into .agents/skills/. The tool also maintained a record of the installed material. The result was a copy in the project, not a live reference to the instruction file inside the dependency.

Once copied, that file can acquire changes of its own.

A controlled lifecycle experiment

The test package, lab_skill_fixture, contains two revisions of an instruction, A and B, with different text. The setup also includes a supporting file, a development dependency, and a transitive dependency—a package brought in through another package rather than declared directly by the application. An unmanaged file was placed in the destination directory as well.

These are deliberately simple fixtures. Their purpose is to make it clear which content was installed, whether it changed, and whether unrelated files survived. No agent was asked to build an application with them.

The experiment ran on Dart SDK 3.13.2, Linux arm64, in isolated containers. Twelve scenarios were each run twice using the same built image. Commands, file snapshots, and interactive input were recorded. The outcomes matched across the two runs. Reinstalling unchanged content preserved the files but updated an installation timestamp; that bookkeeping field was checked separately from the substantive state.

The package-skills-workflow experiment contains the source and reproduction instructions. The verification record documents the scope and limitations. Three situations are particularly relevant to everyday maintenance.

An upstream update meets a local edit

Revision A was installed first, then the installed copy was edited locally. In an actual project, that edit might add the team's error-handling convention or a restriction on changing the module layout.

The dependency was then switched to revision B. Both revisions were local directories referenced through path dependencies. This was a controlled change of source, not a test of upgrading a hosted package through pub.dev.

The tool now had to deal with two diverging texts: the package author's new revision and the installed copy containing local changes. In interactive mode, it displayed the skill with the label Local edits and left it unselected by default.

Submitting the empty selection preserved the local bytes. Explicitly selecting the skill replaced them with revision B. The tool did not merge the two texts in this scenario.

Keeping the local copy also means not receiving the author's changes. Replacing it means losing the added rules. If both are needed, someone has to compare the revisions and decide how to combine them.

For that reason, application rules that should survive independently of a particular library update are better kept separate from the managed copy of a package skill. This is a recommendation about organizing the material, not a promise about instruction precedence. How an agent handles conflicting instructions is a separate concern.

What --all changes

The tool provides --all for operations without manual skill selection. In the experiment, it was applied to the selected package. The starting conflict was the same: a locally edited copy of A and revision B in the dependency.

With skills 1.0.1, that invocation replaced the local instruction with B without presenting a selection dialog.

That behavior can be appropriate when installed skills are treated as unmodified copies of dependency-provided material. It is incompatible with an expectation that edits made directly to those copies will be preserved automatically.

Before adding the command to an update script, the team needs to decide who owns the installed content. If the package author is its sole source, updates should restore that author's revision. If the team also edits those files, it needs history and a review of the differences. The flag cannot make that policy decision for the project.

This observation is limited to the tested conflict and tool version. It does not establish that --all suppresses every possible prompt for every source type. Separate Git sources, for example, were outside the experiment.

Removing a dependency does not finish the cleanup

Another case removed the package from pubspec.yaml and ran pub get. The dependency was gone, but its installed instruction remained.

Dependency resolution and management of copied instructions are separate operations. That explains the result, but it does not make the remaining file any less relevant: the project can still contain advice for a library it no longer uses.

In one scenario, an explicit prune --all removed the instruction. In another, a subsequent get performed the cleanup. The manually added, unmanaged file survived. Selective removal of one skill also preserved an installed skill belonging to another dependency.

This adds a small maintenance task when replacing a library. Alongside checking dependency declarations, imports, and leftover code, inspect the instructions associated with the old package. The reason is not that every remaining file will necessarily be used by an agent. It is that the project's available guidance should have a clear purpose and remain current.

A useful starting point

Start with one dependency and one instruction that addresses a recurring problem. Read it, check that it applies to the installed version, and install it in a separate project. Inspect the changed files before deciding how updates should fit into the team's workflow.

Package authors can approach the problem from the other direction: choose a common misuse and explain the decision that prevents it. In the ark_mvp example, that means distinguishing information that must remain available from an action intended only for the active UI. A concrete rule tied to the library's contract is more useful than a general instruction to follow good architecture.

Once skills are installed, their changes deserve attention alongside dependency changes. A Markdown file can recommend a different way to structure code. Coming from a familiar package does not remove the need to read its contents, nor does it grant permission to carry out additional actions in the project.

The experiment does not measure whether these materials improve a model's output. That would require a separate comparison on equivalent tasks, with an assessment of the resulting code. What it establishes is narrower: how instructions enter a project, what happens when revisions conflict, and how the installed files are removed.

Package skills give library authors a way to maintain guidance for agents alongside their code. For a team using that guidance, the practical value depends on understanding where it comes from and how it changes. Installing the first skill is straightforward. Deciding what should happen to it at the next project update is the part worth settling early.

---

More engineering articles: ArkTelos Lab. Packages and project news: the official ArkTelos website.

Channels: Lab EN | Lab RU | ArkTelos EN | ArkTelos RU.