Ship skills with packages

When developers use your Dart or Flutter package, their AI coding agents, such as Cursor, Gemini, Claude Code, Cline, and Copilot, rely on context to write accurate, idiomatic code.

By shipping agent skills directly with your package, you provide AI agents with authoritative instructions, code examples, and best practices tailored specifically to your library's APIs. To learn how developers install and use skills in their projects, see Package skills.

Without skills, AI coding agents often guess APIs, suggest deprecated methods, or miss architectural patterns specific to your library. When you publish skills alongside your package:

• Fewer developer errors: Agents generate working, idiomatic code on the first try.
• Reduced support burden: Common setup pitfalls and anti-patterns are proactively prevented.
• Seamless installation: Consumers of your package can install your skills with a single command: dart run skills@ get.

A package skill is a set of guidelines and examples that teaches an AI agent how to use a specific part of your library. When planning skills for your package:

• Focus on common workflows: Create skills for key tasks, such as initial setup, routing, authentication, error handling, or performance optimization.
• Keep skills modular: Create separate, focused skills for distinct feature areas (for example, my_package-routing and my_package-auth) rather than bundling everything into one large skill.
• Write prescriptive instructions: Use direct, unambiguous rules (such as "Always initialize X before calling Y") rather than open-ended explanations.

To provide skills in your package, create a top-level skills/ directory at the root of your package, alongside lib/ and pubspec.yaml:

my_package/
├── lib/
├── skills/
│   ├── my_package-routing/
│   │   ├── SKILL.md
│   │   ├── scripts/       # Optional helper scripts
│   │   ├── references/    # Optional reference docs
│   │   └── assets/        # Optional static resources
│   └── my_package-testing/
│       └── SKILL.md
└── pubspec.yaml

Each subdirectory in skills/ represents a single skill and must contain a SKILL.md file following the open Agent Skills specification.

To prevent naming collisions when consumers install skills from multiple dependencies, every skill directory name must begin with your package name (or your package name with underscores replaced by hyphens) followed by a hyphen:

Each skill is defined in a SKILL.md file with YAML frontmatter and Markdown instructions.

The following template illustrates the structure of a SKILL.md file that you can customize for your package:

---
name: <package_name>-<skill_name>
description: >-
  Use when the user is working with <package_name> APIs to ensure correct
  patterns and error handling.
---
​
# <Skill Title>
​
## Guidelines
​
* Always call `initialize()` before invoking other methods.
* Prefer using `<SpecificException>` over generic `Exception` types.
* Dispose of controllers and streams when they are no longer needed.
​
## Examples
​
### Basic setup example
​
```dart
import 'package:<package_name>/<package_name>.dart';
​
void main() {
  // Provide clear, idiomatic Dart code snippets for the agent to follow.
}
```

A SKILL.md file typically consists of three parts:

• YAML frontmatter (name, description): Identifies the skill and tells the AI coding agent when to activate the skill based on the user's prompt.
• Guidelines: A list of direct, prescriptive rules describing library conventions, recommended patterns, and common anti-patterns to avoid.
• Examples: Copy-pasteable Dart code snippets showing how to implement common tasks using your library's APIs.

You can use the package:skills CLI to quickly scaffold a new skill in your current package:

$ dart run skills@ create -n <skill_name> -d "<skill_description>"

This command automatically generates the prefixed directory and a starter SKILL.md template.

When developing your package, distinguish between skills used internally for package development and skills published for your package consumers:

Before you publish your package, use package:skills_lint to validate your skills against the Agent Skills specification. The linter checks SKILL.md YAML frontmatter, directory structure, package naming conventions, and relative file paths to keep your skill definitions valid and ready for AI assistants to use.

Add skills_lint to your package's dev_dependencies:

$ dart pub add dev:skills_lint

After you add skills_lint as a dev dependency, install its bundled skills with dart run skills@ get. Then provide your AI coding agent the following prompt:

Use the skills-lint-setup skill to set up skills_lint in this package
so that `dart test` fails when a skill in skills/ is invalid. Then use
the skills-lint-validation skill to run the linter and fix any failures.

To configure and run skills_lint manually instead, you can pass command-line flags or create a skills_lint.yaml file.

To validate the skills in a directory, run the following command:

$ dart run skills_lint --skills-directory <skills_directory>

Replace <skills_directory> with the path to your skills directory, such as skills/.

You can pass additional flags to customize validation. For all available flags and automatic fix options, run dart run skills_lint --help or consult the package:skills_lint documentation.

For example, to validate your package's skills/ directory with package naming and relative path checks enabled, run the following command:

$ dart run skills_lint --skills-directory skills/ --published-skill-name --check-relative-paths

To enforce consistent rules across local runs and continuous integration (CI) without passing flags every time, create a skills_lint.yaml file at the root of your package. Start from the following recommended configuration and adjust the paths for your package:

# skills_lint.yaml
skills_lint:
  rules:
    check-relative-paths: error
    check-absolute-paths: error
  directories:
    - path: "skills/"
      rules:
        published-skill-name: error
    - path: ".agents/skills/"
  individual_skills:
    - path: "my_custom_standalone_skill"
      rules:
        check-trailing-whitespace: warning

After you add the skills_lint.yaml file, run the linter with no arguments:

$ dart run skills_lint

Consult the package:skills_lint documentation for details on rule precedence, built-in rules, and custom rule authoring.

To catch invalid skills automatically during local test runs and in your existing dart test CI workflow, add a test under test/ that runs skills_lint against your skills_lint.yaml configuration and fails when the linter reports errors.

For standalone CI workflows or Git pre-commit hooks, consult Recipes in the package:skills_lint documentation.

Before publishing your package to pub.dev, verify that your skills can be discovered and installed properly:

1. Create a sample Dart or Flutter project to act as a consumer.

2. In the sample project's pubspec.yaml, add a path dependency pointing to your local package:

   yaml

   dependencies:
     my_package:
       path: ../path/to/my_package
   

   content_copy

3. Run dart run skills@ get in the sample project.

4. Verify that your skills appear in the interactive selection prompt and install cleanly into the sample project's .agents/skills/ directory.

When you publish your package with dart pub publish, the skills/ directory is automatically bundled into the package archive. Once published, consumers who depend on your package can install your skills by running dart run skills@ get.

• Keep skills focused: Create one skill per major feature area rather than a single oversized skill.
• Write for the AI agent: Use clear, prescriptive instructions. Direct rules (such as "Always use X before calling Y") are more effective than open-ended narrative text.
• Include concrete code examples: Show complete, working code snippets illustrating idiomatic Dart API usage.
• Keep SKILL.md concise: Keep SKILL.md under 500 lines. Place extensive reference materials, schemas, or large documentation tables in subdirectories like references/ or assets/.
• Version skills with your package: When updating your package APIs in new versions, update your skills to reflect the latest recommendations.

• package:skills on pub.dev
• package:skills_lint on pub.dev
• Agent Skills specification