diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 41fccc5a..a5425a9e 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.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 `` must include a `title` prop that names the integration, workflow, feature, or task shown. ✅ `` ❌ `` 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: diff --git a/.agents/templates/feature-doc.md b/.agents/templates/feature-doc.md index 4f3d24ca..d3bb081e 100644 --- a/.agents/templates/feature-doc.md +++ b/.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. diff --git a/.agents/templates/guide-page.md b/.agents/templates/guide-page.md index 31c93e13..6d76b6e6 100644 --- a/.agents/templates/guide-page.md +++ b/.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'; */} - +{/* VIDEO: Always include a specific title prop naming the workflow/feature shown. Remove the entire VideoEmbed block if there is no video. */} + ## Prerequisites