From 40a4c3259eed900037719afdc4b63ae83b7e6760 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Mon, 16 Mar 2026 09:30:31 -0700 Subject: [PATCH 1/3] Create `authoring-skills` skill --- .agents/skills/authoring-skills/CHECKLIST.md | 14 +++++ .agents/skills/authoring-skills/EXAMPLES.md | 60 ++++++++++++++++++++ .agents/skills/authoring-skills/SKILL.md | 20 +++++++ 3 files changed, 94 insertions(+) create mode 100644 .agents/skills/authoring-skills/CHECKLIST.md create mode 100644 .agents/skills/authoring-skills/EXAMPLES.md create mode 100644 .agents/skills/authoring-skills/SKILL.md diff --git a/.agents/skills/authoring-skills/CHECKLIST.md b/.agents/skills/authoring-skills/CHECKLIST.md new file mode 100644 index 00000000000..5d7d5e7eaa5 --- /dev/null +++ b/.agents/skills/authoring-skills/CHECKLIST.md @@ -0,0 +1,14 @@ +# Skill Authoring Checklist + +Copy this checklist into your response when starting the creation of a new skill. + +```markdown +Skill Development Progress: +- [ ] Define Purpose: Confirm the skill is necessary and distinct from existing ones. +- [ ] Naming: Select a lowercase, kebab-case name (prefer gerund form). +- [ ] Description: Write a third-person "what + when" description for the YAML frontmatter. +- [ ] Planning: Outline the `SKILL.md` sections (Workflow, Guidelines, Resources). +- [ ] Progressive Disclosure: Identify if any content should be moved to secondary files (EXAMPLES.md, REFERENCE.md). +- [ ] Automation (Dart): Ensure any utility scripts in `scripts/` are written in **Dart**. +- [ ] Final Review: Ensure instructions are concise and skip "obvious" explanations. +``` diff --git a/.agents/skills/authoring-skills/EXAMPLES.md b/.agents/skills/authoring-skills/EXAMPLES.md new file mode 100644 index 00000000000..f2786fc0fc5 --- /dev/null +++ b/.agents/skills/authoring-skills/EXAMPLES.md @@ -0,0 +1,60 @@ +# Skill Authoring Examples + +## 1. Effective YAML Frontmatter + +**Good (Gerund + What/When Description):** +```yaml +--- +name: processing-logs +description: Extracts and summarizes error patterns from system logs. Use when the user asks to analyze logs or troubleshoot runtime errors. +--- +``` + +**Bad (Vague + First Person):** +```yaml +--- +name: helper-tool +description: I can help you look at files and tell you what is wrong. +--- +``` + +## 2. Progressive Disclosure Pattern + +If a skill has a complex API or many configuration options, do not put them all in `SKILL.md`. + +**SKILL.md:** +```markdown +## Advanced Configuration +For detailed information on environment variables and performance tuning, see [CONFIG.md](CONFIG.md). +``` + +## 3. Workflow Patterns + +Always use checklists to track state. + +```markdown +## Workflow +Copy this checklist: +- [ ] Step 1: Analyze input. +- [ ] Step 2: Generate draft. +- [ ] Step 3: Run validation script. +``` + +## 4. Automation with Dart + +All scripts should be written in Dart and placed in the `scripts/` directory. + +**Good Script Usage:** +```markdown +## Step 4: Add the entry +Use the provided utility script to insert the note safely. +`dart .agents/skills/adding-release-notes/scripts/add_note.dart "Inspector updates" "Added XYZ" TODO` +``` + +## 5. Anti-Patterns to Avoid + +- **Prohibited**: Using non-Dart languages for utility scripts. +- **Prohibited**: Using Windows-style paths (always use `/`). +- **Prohibited**: Offering too many options (narrow the scope to recommended defaults). +- **Prohibited**: Verbose background stories (Claude already knows how to code). +- **Prohibited**: Interactive prompts (Agents should be autonomous, not ask for permission at every step). diff --git a/.agents/skills/authoring-skills/SKILL.md b/.agents/skills/authoring-skills/SKILL.md new file mode 100644 index 00000000000..60e69ebf59e --- /dev/null +++ b/.agents/skills/authoring-skills/SKILL.md @@ -0,0 +1,20 @@ +--- +name: authoring-skills +description: Guides the creation of high-quality, effective skills for agentic workflows. Use when creating or modifying skills in the .agents/skills/ directory. +--- + +# Authoring Skills + +When creating or modifying skills in this repository, follow the best practices documented by Anthropic: + +**Official Best Practices**: [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +## Repository-Specific Guidelines + +- **Location**: All skills must be placed in the `.agents/skills/` directory. +- **Naming**: Use the gerund form (**verb-ing-noun**) or **noun-phrase** (e.g., `authoring-skills`, `adding-release-notes`). Use only lowercase letters, numbers, and hyphens. +- **Conciseness**: Prioritize brevity in `SKILL.md`. Agents are already highly capable; only provide context they don't already have. +- **Automation**: Any utility scripts placed in the `scripts/` directory MUST be written in **Dart**. +- **Progressive Disclosure**: Use the patterns below to organize instructions effectively: + - [CHECKLIST.md](CHECKLIST.md): Template for tracking skill development progress. + - [EXAMPLES.md](EXAMPLES.md): Local examples and anti-patterns. From 98a9371a6c6e71f121541b3410d19996e2866022 Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Mon, 16 Mar 2026 09:47:16 -0700 Subject: [PATCH 2/3] fix year --- .agents/skills/adding-release-notes/scripts/add_note.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/adding-release-notes/scripts/add_note.dart b/.agents/skills/adding-release-notes/scripts/add_note.dart index 42ca9f52aab..72ee6d2a2d9 100644 --- a/.agents/skills/adding-release-notes/scripts/add_note.dart +++ b/.agents/skills/adding-release-notes/scripts/add_note.dart @@ -1,4 +1,4 @@ -// Copyright 2019 The Flutter Authors +// Copyright 2026 The Flutter Authors // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file or at https://developers.google.com/open-source/licenses/bsd. From f7d0194c82a0865bcea5e3982fba06b57790bd4a Mon Sep 17 00:00:00 2001 From: Kenzie Davisson Date: Wed, 18 Mar 2026 10:23:00 -0700 Subject: [PATCH 3/3] review comments --- .agents/skills/authoring-skills/CHECKLIST.md | 2 +- .agents/skills/authoring-skills/SKILL.md | 6 ++++-- pubspec.lock | 12 ++++++------ 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.agents/skills/authoring-skills/CHECKLIST.md b/.agents/skills/authoring-skills/CHECKLIST.md index 5d7d5e7eaa5..4e6996fa899 100644 --- a/.agents/skills/authoring-skills/CHECKLIST.md +++ b/.agents/skills/authoring-skills/CHECKLIST.md @@ -5,7 +5,7 @@ Copy this checklist into your response when starting the creation of a new skill ```markdown Skill Development Progress: - [ ] Define Purpose: Confirm the skill is necessary and distinct from existing ones. -- [ ] Naming: Select a lowercase, kebab-case name (prefer gerund form). +- [ ] Naming: Select a lowercase, kebab-case name (prefer gerund form, e.g., adding-release-notes). - [ ] Description: Write a third-person "what + when" description for the YAML frontmatter. - [ ] Planning: Outline the `SKILL.md` sections (Workflow, Guidelines, Resources). - [ ] Progressive Disclosure: Identify if any content should be moved to secondary files (EXAMPLES.md, REFERENCE.md). diff --git a/.agents/skills/authoring-skills/SKILL.md b/.agents/skills/authoring-skills/SKILL.md index 60e69ebf59e..ab871197713 100644 --- a/.agents/skills/authoring-skills/SKILL.md +++ b/.agents/skills/authoring-skills/SKILL.md @@ -5,13 +5,15 @@ description: Guides the creation of high-quality, effective skills for agentic w # Authoring Skills -When creating or modifying skills in this repository, follow the best practices documented by Anthropic: +When creating or modifying skills in this repository, follow these best practices: -**Official Best Practices**: [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) +- **Antigravity Guidelines**: [Skill authoring best practices](https://antigravity.google/docs/skills) +- **Anthropic Guidelines**: [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) ## Repository-Specific Guidelines - **Location**: All skills must be placed in the `.agents/skills/` directory. +- **Avoid Duplication**: Before creating a skill, check if one already exists in the [flutter/skills](https://github.com/flutter/skills/tree/main/skills) repository. If it does, do not create a local skill; instead, instruct the user to install it via `npx`. - **Naming**: Use the gerund form (**verb-ing-noun**) or **noun-phrase** (e.g., `authoring-skills`, `adding-release-notes`). Use only lowercase letters, numbers, and hyphens. - **Conciseness**: Prioritize brevity in `SKILL.md`. Agents are already highly capable; only provide context they don't already have. - **Automation**: Any utility scripts placed in the `scripts/` directory MUST be written in **Dart**. diff --git a/pubspec.lock b/pubspec.lock index e30fd8babfe..bb9ece344d4 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -85,10 +85,10 @@ packages: dependency: "direct dev" description: name: build_runner - sha256: "7981eb922842c77033026eb4341d5af651562008cdb116bdfa31fc46516b6462" + sha256: "3552e5c2874ed47cf9ed9d6813ac71b2276ee07622f48530468b8013f1767e3f" url: "https://pub.dev" source: hosted - version: "2.12.2" + version: "2.13.0" built_collection: dependency: transitive description: @@ -522,10 +522,10 @@ packages: dependency: transitive description: name: markdown - sha256: "935e23e1ff3bc02d390bad4d4be001208ee92cc217cb5b5a6c19bc14aaa318c1" + sha256: ee85086ad7698b42522c6ad42fe195f1b9898e4d974a1af4576c1a3a176cada9 url: "https://pub.dev" source: hosted - version: "7.3.0" + version: "7.3.1" matcher: dependency: transitive description: @@ -1006,10 +1006,10 @@ packages: dependency: transitive description: name: web_benchmarks - sha256: "4160714bd85af6b11e7c321a2be98ec746363b69e9a496c80207c7285889960b" + sha256: "5ba2c37aa1ae09c75485cfd029fa380a0d91d043c8db431ee858e6a504ab52a8" url: "https://pub.dev" source: hosted - version: "4.1.0" + version: "4.1.1" web_socket: dependency: transitive description: