Create `authoring-skills` skill (#9716)
diff --git a/.agents/skills/adding-release-notes/scripts/add_note.dart b/.agents/skills/adding-release-notes/scripts/add_note.dart
index 42ca9f5..72ee6d2 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.
diff --git a/.agents/skills/authoring-skills/CHECKLIST.md b/.agents/skills/authoring-skills/CHECKLIST.md
new file mode 100644
index 0000000..4e6996f
--- /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, 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).
+- [ ] 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 0000000..f2786fc
--- /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 0000000..ab87119
--- /dev/null
+++ b/.agents/skills/authoring-skills/SKILL.md
@@ -0,0 +1,22 @@
+---
+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 these 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**.
+- **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.
diff --git a/pubspec.lock b/pubspec.lock
index e30fd8b..bb9ece3 100644
--- a/pubspec.lock
+++ b/pubspec.lock
@@ -85,10 +85,10 @@
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 @@
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 @@
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:
