feat: add YAML frontmatter to handoff skill

skills/handoff/SKILL.md

@@ -1,3 +1,16 @@
+---
+name: handoff
+description: >
+  Builds a complete task order package for a subcontractor AI tool (ChatGPT, Gemini, etc.)
+  to analyze Gmail labels and propose classification rules. Use when the user says "create
+  the task orders", "set up the handoff", "build the task orders", "I want to hand this off
+  to ChatGPT", "prepare the handoff package", or "send this to another AI". Also invoked
+  automatically by the survey skill when inbox volume exceeds the inline sampling threshold.
+  Produces a Drive folder with prompt, context, label inventory, and output schema — the user
+  delivers it to the subcontractor and brings results back via the import skill.
+  Part of the Gmail Inbox Architect plugin.
+---
+
 # handoff — Gmail Inbox Architect
 
 ## What This Skill Does
@@ -191,24 +204,26 @@ You have direct access to the Gmail account. Use that access as you see fit to i
 sender patterns, domain signals, subject patterns, and attachment types — whatever gives
 you confident rule proposals.
 
-Return your findings using the exact schemas in OUTPUT_FORMAT.md:
+Return your findings using the schemas in OUTPUT_FORMAT.md. Preferred format is three CSVs,
+but return whatever format works best for your tool — Claude's import skill can normalize
+any reasonable structured output (CSV, XLSX, Markdown tables, JSON, etc.).
 
-  filter_rules.csv       — rules Gmail can execute natively (domain, subject, participant)
+  filter_rules      — rules Gmail can execute natively (domain, subject, participant pattern)
-  apps_script_rules.csv  — rules requiring attachment filename/extension inspection
+  apps_script_rules — rules requiring attachment inspection, body text signals, or multi-condition logic
-  taxonomy_notes.csv     — taxonomy gaps, policy observations, and anything needing review
+  taxonomy_notes    — taxonomy gaps, policy observations, anything needing Claude's review
+  studio_candidates — (optional) fuzzy or semantic rules that don't fit filter or script logic
 
 If the label inventory is large and you prefer to work in batches, propose a batching
 plan and execute the first batch. Subsequent task orders will be prepared for remaining work.
 
-Hard constraints that must be respected:
+Constraints to respect:
 - Participant-domain logic (from OR to OR cc) for client and reseller labels
 - From-only logic for vendors, services, and financial senders
-- No rules dependent on message body text — filters and Apps Script work from headers,
+- Gmail native filters cannot inspect message body text — propose those as apps_script_needed rules
-  subjects, and attachment filenames only
+- Document your basis for every proposed rule in the notes field
-- Document your basis for every proposed rule in the notes column
+- Use "do_not_automate_yet" status for anything you are not confident about
-- Use taxonomy_notes.csv status "do_not_automate_yet" for anything you are not confident about
 
-Return all three CSV files. Do not summarize — just return the files.
+Return your results. Do not summarize — just return the data.
 ```
 
 **PROMPT.md template (Generic / Unknown tool):**
@@ -360,13 +375,16 @@ notes           — REQUIRED. Your basis: what emails triggered this proposal an
 
 ## File 2: apps_script_rules.csv
 
-Rules that require attachment filename/extension inspection. Use ONLY for rules where
+Rules that require Apps Script to execute. Use for: attachment filename/extension patterns,
-the trigger is an attachment file type or naming pattern.
+message body text signals, multi-condition logic beyond Gmail filter capabilities, or any
+rule that requires reading the email content beyond headers and subjects.
 
 Same columns as filter_rules.csv, with these differences:
 rule_id         — Format: AS-[CATEGORY]-[DESCRIPTION] e.g. AS-DOC-STEP-FILE
 deployability   — Always: apps_script_needed
-notes           — Must include: exact filename pattern (e.g. *.stp, *.step, inv-*.pdf)
+notes           — REQUIRED. Include the specific signal (filename pattern, body keyword,
+                  logic condition) that requires Apps Script. e.g. "body contains 'PO#';
+                  attachment *.stp; subject + sender combination not filterable natively"
 
 ---
 
@@ -392,10 +410,13 @@ notes           — Additional context. For do_not_automate_yet: explain what wo
 
 ## Important Notes
 
-- Return ALL THREE files even if one has zero rows (include header row only)
+- The CSV format above is preferred but not required — return whatever your tool handles best
-- Do not return the files as code blocks — attach them as actual CSV files
+- If returning CSVs: include header row even for empty files
-- Do not summarize or explain in chat — just return the files
+- If returning another format (Markdown tables, JSON, XLSX): Claude's import skill will normalize it
-- If you are unsure about something, put it in taxonomy_notes.csv with status do_not_automate_yet
+- Do not summarize or explain in chat — just return the data
+- If you are unsure about something, flag it with status "do_not_automate_yet" and explain why
+- If a rule requires semantic or AI-based classification that filters and Apps Script can't handle,
+  flag it as a studio_candidate with a description of what signal you'd use
 ```
 
 ---
@@ -439,8 +460,6 @@ Notes: Batches created: [list batch names]. Each returns 3 CSV files to import.
 
 ---
 
----
-
 ## Embedded Template: Rule ID Format
 
 ```
@@ -474,5 +493,3 @@ FINANCE / VENDOR / CLIENT / OPS / DEV / SALES / TRAVEL / NOTIF / SUPPORT / DOC /
    brings results back to Claude. Deploy skill executes. Nothing is automatic.
 
 5. The subcontractor proposes. Claude decides. Always.
-
-