docs: add agent skills playbook for technical writers

.agents/skills/doc_comparative_layout_builder/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: doc-comparative-layout-builder
+description: Identifies duplicate workflow explanations and builds comparative tables using Jekyll styles.
+---
+
+# Comparative Layout Builder
+
+## Overview
+
+Use this skill to refactor technical documents to present cross-platform options in side-by-side matrices instead of disjointed sections, and style them correctly using the repository's native styling tags.
+
+## Workflow
+
+### 1. Identify Redundant Sections
+
+- [ ] Scan tutorials comparing different lanes of code (e.g. Method Channels vs. generated bindings) to identify parallel sections (like "Overview JNIgen" next to "Overview Channels").
+- [ ] Collapse distinct overviews into a single consolidated **"Overview: Bindings vs. Channels"** section.
+
+### 2. Format a Core Choice Table
+
+- [ ] Construct a comparative table detailing:
+  - **Integration Option**: The names of the methods.
+  - **When to Use**: Clear situations favoring the approach.
+  - **Tradeoffs / When Not to Use**: Limitations, compile speed, or complexity factors.
+- [ ] Add a short summary explaining how options are **non-exclusive** and can be combined inside complex codebases (e.g. FFI for C, Pigeon for API bridges).
+
+### 3. Apply Style Decorations
+
+- [ ] Verify that every markdown table is directly followed by the Jekyll/Kramdown class helper line:
+  ```markdown
+  {:.table .table-striped}
+  ```
+- [ ] Spin up the local preview compiler server to verify that the table renders with correct borders, padding, and striping layout.

.agents/skills/doc_create_custom_agent_skills/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: doc-create-custom-agent-skills
+description: Analyzes past chat logs and summaries to formulate new technical writing agent skills.
+---
+
+# Create Custom Agent Skills (Meta-Skill)
+
+## Overview
+
+Use this skill to extract recurring workflow patterns from a completed or in-progress conversation and package them into formal, reusable `.agents/skills/` playbooks.
+
+## Workflow
+
+### 1. Review Conversation Transcript
+
+- [ ] Scan the chat logs and summaries in the workspace.
+- [ ] Identify repetitive or highly structured tasks that were performed, such as:
+  - Repetitive text auditing (pronouns, formatting, code gotchas).
+  - Component or layout conversions (collapsing items into comparisons, tables).
+  - Configuration files edits (sidebars, paths, links validation).
+  - Validation steps (CUJ auditing, compile testing).
+
+### 2. Group into Skill Scopes
+
+- [ ] Deconstruct each recurring task into a dedicated, single-purpose skill scope. Avoid creating overloaded skills that try to solve multiple distinct objectives at once.
+- [ ] For each identified skill scope, define:
+  - **`name`**: Kept short, lowercase, and hyphenated (e.g. `doc-migration-setup`).
+  - **`description`**: A single bullet-like summary details what the skill delivers.
+
+### 3. Write the Skill Blueprint
+
+- [ ] Create a new directory under `.agents/skills/[skill_type]/` matching the name.
+- [ ] Write a `SKILL.md` containing the frontmatter block at the top:
+  ```markdown
+  ---
+  name: [skill-name]
+  description: [Short explanation of what the skill does.]
+  ---
+  ```
+- [ ] Add the following markdown layout inside `SKILL.md`:
+  - `# Skill Title`
+  - `## Overview`: A paragraph describing the target persona and benefits.
+  - `## Workflow`: A checklist of actionable, itemized instructions that lead the agent from input collection to final validation.
+
+### 4. Create the Playbook Pull Request
+
+- [ ] Add the folders to Git.
+- [ ] Commit and push the branch to your fork to open the Pull Request.

.agents/skills/doc_linguistic_technical_audit/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: doc-linguistic-technical-audit
+description: Scans technical documentation files for pronoun voice and code-gotcha explanations.
+---
+
+# Linguistic & Technical Audit
+
+## Overview
+
+Use this skill to audit markdown files to ensure they conform to stylistic voice guidelines and clearly explain code caveats (such as manual reference counting or class naming overrides) so readers do not get blocked.
+
+## Workflow
+
+### 1. Pronoun and Voice Sweep
+
+- [ ] Search the modified files for institutional passive pronouns: "we", "us", "our", and "one".
+- [ ] Rewrite sentences containing these pronouns to use the second person (**"you"**) or passive-free active instructions.
+  - *Incorrect*: "Next, we will call compile to build the apk."
+  - *Correct*: "Next, run the compile command to build the APK."
+- [ ] Check sentence boundaries to ensure no descriptions end in incomplete lines or abrupt breaks.
+
+### 2. Prerequisite Script Optimization
+
+- [ ] Check setup block build instructions. Look for bloated compile steps (such as `flutter build apk` or `flutter build ipa`) when local dependencies fetching or lightweight options (like `flutter pub get`) are sufficient.
+- [ ] Replace heavy build stages with faster caching triggers to save developer time.
+
+### 3. API Gotcha Documentation
+
+- [ ] If the documentation guides developers in using generated API bindings, verify that memory reference behaviors are covered:
+  - Explain how native JNI or ObjC pointers are held.
+  - Standardize reference instructions explaining how/when to release resources (e.g. calling `.release()` or utilizing pointers cleanup blocks).
+- [ ] Check generated overloaded signatures (e.g. methods mapped with numeric suffixes like `methodName$1` or pointers overrides). Explain to the reader why the suffix exists and how to map it to the original overloaded method name.

.agents/skills/doc_migration_setup/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: doc-migration-setup
+description: Establishes a context profile and migration checklist before editing files.
+---
+
+# Document Migration Setup
+
+## Overview
+
+Use this skill to correctly pull together base files, comments, and outline drafts when preparing to rewrite or migrate a documentation section (e.g. moving from Method Channels to Native Interop).
+
+## Workflow
+
+### 1. Collect Context Base Files
+
+- [ ] Ask the user for the URL of the base Pull Request or Git branch to fetch.
+- [ ] Ask the user for the text document outlines or notes detailing the new feature's design.
+- [ ] Ask the user for the reviewer comments spreadsheet, tracking sheet, or text files holding previous developer threads.
+
+### 2. Run Gap & File Status Analysis
+
+- [ ] Inspect the repository directory structures. Compare the old folder structure with the user's intent:
+  - List files to be **Modified**.
+  - List files to be **Created** (new page paths).
+  - List files to be **Deleted** (deprecated pages).
+- [ ] Build a **File Status Matrix** mapping change scopes to target paths.
+
+### 3. Create the Execution Log & Checklist
+
+- [ ] Write an `implementation_plan.md` artifact grouping tasks by Phase (e.g. Phase 1: Landing Page, Phase 2: Android Interop, Phase 3: iOS framework).
+- [ ] Write a `task.md` file listing granular checklist check-boxes tracking subtasks.
+- [ ] Outline a preliminary **Verification Plan** detailing how results will be checked (e.g., compile steps, anchor validation).

.agents/skills/doc_navigation_taxonomy_editor/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: doc-navigation-taxonomy-editor
+description: Sweeps and refactors website sidebar configuration (default.yml) to organize categories and check links.
+---
+
+# Sidebar Navigation Taxonomy Editor
+
+## Overview
+
+Use this skill to inspect and clean the documentation's side navigation config (typically `default.yml`), re-organize the layout into option groups, check for broken URLs, and remove review draft markers.
+
+## Workflow
+
+### 1. Remove Temporary Review Labels
+
+- [ ] Scan the header nodes in the Yaml child configurations. Locate and remove words like:
+  - `(new)`
+  - `(old)`
+  - `(restructured)`
+  - `(draft)`
+- [ ] Save changes while preserving the indentation spacing (YAML syntax is whitespace-specific).
+
+### 2. Group Options and Platforms
+
+- [ ] Group general integration parameters at the top of the category's children:
+  1. *General options and table choice guides.*
+  2. *General binary linkers FFI.*
+  3. *General channels messaging Pigeon.*
+- [ ] Group platform setup guides below a divider target:
+  - Use `- divider` to visually separate general layout choices from target operating systems.
+  - Nest iOS, macOS, Windows, Linux, Android, and Web files below.
+- [ ] Ensure specific OS operations (e.g. build desktop stages) are housed inside their platform directories to prevent duplication.
+
+### 3. Validate Link Integrity
+
+- [ ] Check every permalink defined in the sidebar configurations. Verify that:
+  - The destination `.md` file exist in the source paths.
+  - The page title is consistent with the sidebar title.
+- [ ] Verify that parent-child configurations compile without indentation syntax errors.

.agents/skills/doc_user_journey_test/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: doc-user-journey-test
+description: Executes user persona runs (CUJs) and writes walkthrough validation logs.
+---
+
+# User Journey Validation (CUJ)
+
+## Overview
+
+Use this skill to audit newly crafted or refactored documentation from the perspective of specific developer profiles, verify links, and summarize results in walking indexes.
+
+## Workflow
+
+### 1. Define CUJ Personas
+
+- [ ] Identify 2–3 target developer profiles who will consume the documentation. Examples:
+  - **Persona A (The Flutter Native Beginner)**: Familiar with Flutter but has never written Kotlin/Swift or set up platform-specific paths.
+  - **Persona B (The Plugin Architect)**: Needs to bind complex external C++ libraries or third-party Maven/CocoaPods components.
+- [ ] List the questions each persona is asking when landing on the page.
+
+### 2. Run the Reading Journey
+
+- [ ] "Read" each draft file chronologically pretending to be the target persona. Fulfill the code steps step-by-step.
+- [ ] Flag and repair:
+  - Missing commands or prerequisites (e.g. telling a user to configure a file without showing them where it goes).
+  - Vague naming declarations.
+  - Unexplained technical terminology (e.g. JNI reference count management, FFI timer callbacks).
+
+### 3. Create the Walkthrough Log
+
+- [ ] Write a `walkthrough.md` file listing all modifications and new documents.
+- [ ] Detail the visual changes, table adjustments, and compile fixes.
+- [ ] Add explicit instructions on how developers can spin up the local development servlets to visually check the updates.