.agents/skills/README.md

# 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#naming-conventions).
5. **Standard Compliance**: The skill must follow the open standard specification outlined at [https://agentskills.io/specification](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:

```bash
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:
```bash
dart test test/validate_skills_test.dart
```

For example, to check everything and preview fixes, you can run:
```bash
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.