docs(skills): improve drafting skills from signal log patterns 2026-08-05

.agents/skills/draft_docs/SKILL.md

@@ -93,6 +93,8 @@ These rules are frequently violated by agents. Apply them carefully during draft
 - **Tables or parallel bullets for comparison and reference data** — When you present two or more parallel items (key types, plan tiers, environments) or structured reference data (API endpoints, parameters), use a Markdown table or tightly parallel bullets instead of one dense paragraph. ✅ a table with one row per API endpoint, or parallel `**Personal API keys**` / `**Agent API keys**` bullet groups ❌ a single paragraph mixing both key types and their billing rules
 - **Bold for UI elements** — Use `**Save**` not `` `Save` `` after action verbs like "click"
 - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` ``
+- **Screenshots for hard-to-describe UI** — When a page documents a visual surface (statusline chips, tab bars, settings panes, multi-control layouts), include a screenshot after the prose that introduces that surface. Do not rely on prose alone for chrome that reviewers cannot reconstruct from text. Prefer one well-placed figure over repeating the same surface. Always use descriptive alt text. ✅ a statusline screenshot after the paragraph that names the chips ❌ describing chip layout in a long paragraph with no image when humans keep asking "should we include a screenshot?"
+- **`VideoEmbed` requires a specific `title`** — Every `<VideoEmbed>` must include a `title` prop that names the integration, workflow, feature, or task shown. ✅ `<VideoEmbed url="..." title="Warp Agent CLI conversation transcript walkthrough" />` ❌ `<VideoEmbed url="..." />` or a generic title like `"video"` / `"demo"`
 
 ### 7. Draft the doc
 Create the documentation using the appropriate template from `.agents/templates/`. Follow the structure for the identified content type and all rules in `AGENTS.md`. Each template includes visible bracketed instructions explaining what to put in each section.
@@ -127,6 +129,8 @@ Before presenting the draft, verify against the quality checklist in `AGENTS.md`
 - [ ] Product names with a corresponding entry in `src/data/vars.ts` use the variable syntax (`{VARS.KEY}` in prose, `{{TOKEN}}` in frontmatter) — not hardcoded strings
 - [ ] If AEO-driven, the draft follows the AEO brief, uses source vocabulary naturally, and avoids duplicative or junk-drawer coverage
 - [ ] Images have descriptive alt text
+- [ ] Visual UI surfaces that are hard to reconstruct from prose include a screenshot (or an explicit note that no screenshot is available yet)
+- [ ] Every `VideoEmbed` includes a specific `title` prop describing the workflow or feature shown
 
 ### 10. Update navigation and redirects
 If this is a new page, remind the user to:

.agents/templates/feature-doc.md

@@ -36,6 +36,8 @@ Define new terms when they first appear.
 IMPORTANT: Do NOT include step-by-step procedures in this section.
 Keep the conceptual and procedural sections clearly separated.]
 
+[SCREENSHOTS: If this feature has a distinctive visual surface (statusline, tab bar, side pane, multi-control layout), place a screenshot immediately after the paragraph that introduces that surface. Use descriptive alt text. Skip screenshots for purely textual CLI behavior.]
+
 ## [Usage/configuration section — sentence case. Rename to match the feature, e.g., "Creating environments", "Configuring integrations"]
 
 [PROCEDURAL section: step-by-step instructions.

.agents/templates/guide-page.md

@@ -13,7 +13,8 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 {/* VARS: Also add the line below if this guide references product names from src/data/vars.ts. Then use {VARS.KEY} in prose. Use {{TOKEN}} in frontmatter YAML values above. See AGENTS.md → Content variables. */}
 {/* import { VARS } from '@data/vars'; */}
 
-<VideoEmbed url="[YouTube or Loom URL — remove this block if no video]" />
+{/* VIDEO: Always include a specific title prop naming the workflow/feature shown. Remove the entire VideoEmbed block if there is no video. */}
+<VideoEmbed url="[YouTube or Loom URL]" title="[Specific title: integration, workflow, or task shown — not generic 'video' or 'demo']" />
 
 ## Prerequisites