Flutter Agent Skills

Welcome to the .agent/skills directory. This directory contains agent skills designed for consumption by Flutter contributors.

Requirements for New Skill Adoption

Before landing an initial skill in this shared codebase, the following requirements must be met:

1. Prior Usage: The skill must have been used by the author.
2. Target Audience: The skill must be explicitly designed for use by Flutter contributors.
3. Provide Examples: The pull request adding the skill must include examples of the prompts used with the skill, as well as the output generated by the agent/skill/bot.
4. Naming Conventions: The skill name must follow the established Claude naming conventions.
5. Standard Compliance: The skill must follow the open standard specification outlined at https://agentskills.io/specification.

Ownership and Responsibilities

• Ownership: The author of the skill holds ownership. This means the author is responsible for approving any modifications to the skill and mitigating any negative side effects.
• Succession: If the author can no longer maintain the skill, the author or their manager is responsible for finding a new owner.

Recommended Practices

We encourage contributors to follow these practices when authoring skills, though they are not strictly required:

• Provide Novel Information: Tell the agent what it needs to know, not what it already knows.
• One Skill Per CLI Tool: Create a dedicated skill for each CLI tool. This helps effectively steer the agent on how you want to use it.
• Structure and Rules: Be extremely strict about your style. The more structured and rule-based your instructions are (with a limited number of exceptions), the better. Agents have an exponential reward function for structure.
• Read-Only Mode: When appropriate, tell agents how to access real data strictly in read-only mode to prevent unintended changes.
• Dart Scripts: Scripts should be written in Dart.

Validating Skills

You can manually run the dart_skills_lint tool to validate your skills and fix common issues. Navigate to the dev/tools directory and run:

dart run dart_skills_lint:cli --skills-directory ../../.agents/skills --check-trailing-whitespace --check-absolute-paths --check-relative-paths

Helpful Flags for Authors

• --fix: Preview fixes for failing lints without modifying files (dry run).
• --fix-apply: Automatically apply fixes for fixable rules (like trailing whitespace).
• --check-trailing-whitespace: Enforce no trailing whitespace (except 2 spaces for line breaks).
• --check-absolute-paths: Ensure links do not use absolute paths.
• --check-relative-paths: Ensure relative links point to existing files.

Running Automated Tests

You can also run the automated validation tests from the dev/tools directory:

dart test test/validate_skills_test.dart

For example, to check everything and preview fixes, you can run:

dart run dart_skills_lint:cli --fix --check-trailing-whitespace --check-absolute-paths --check-relative-paths --skills-directory ../../.agents/skills

How to help

If you are a regular contributor looking for areas where you can author a skill, the following are good places to start:

• When to use a command line tool from the repo, its arguments, and how to interpret its outputs.
• How to run a particular set of tests.
• How to run the analyzer or linters that have repo-specific configuration.
• Productization steps that are required after modifying some area of code.
• How to debug or differentiate a common class of issues.