diff --git a/.agents/skills/draft_conceptual/SKILL.md b/.agents/skills/draft_conceptual/SKILL.md index ead9a89ee..305f74cd5 100644 --- a/.agents/skills/draft_conceptual/SKILL.md +++ b/.agents/skills/draft_conceptual/SKILL.md @@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **concept ## Frontmatter description -One sentence, 50-160 characters, saying what the concept is and why it matters. Start with the subject. +One to two sentences, 50-160 characters, saying what the concept is and why it matters. Start with the subject. - ✅ `Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.` - ❌ `Learn about environments and why they are useful.` diff --git a/.agents/skills/draft_faq/SKILL.md b/.agents/skills/draft_faq/SKILL.md index 8358f8ab1..756cf0e20 100644 --- a/.agents/skills/draft_faq/SKILL.md +++ b/.agents/skills/draft_faq/SKILL.md @@ -32,7 +32,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **FAQ tem ## Frontmatter description -One sentence, 50-160 characters, naming the topic area the questions cover. +One to two sentences, 50-160 characters, naming the topic area the questions cover. - ✅ `Answers to common questions about cloud agent billing, credits, and plan limits.` - ❌ `Frequently asked questions.` diff --git a/.agents/skills/draft_feature_doc/SKILL.md b/.agents/skills/draft_feature_doc/SKILL.md index 50d9c02eb..f902127f4 100644 --- a/.agents/skills/draft_feature_doc/SKILL.md +++ b/.agents/skills/draft_feature_doc/SKILL.md @@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **feature ## Frontmatter description -One sentence, 50-160 characters, saying what the feature does and its primary benefit. +One to two sentences, 50-160 characters, saying what the feature does and its primary benefit. - ✅ `Control what the agent can do with permission cards, auto-approve, and execution profiles.` - ❌ `Documentation for permissions and profiles.` diff --git a/.agents/skills/draft_guide/SKILL.md b/.agents/skills/draft_guide/SKILL.md index edd76d929..9001f7eec 100644 --- a/.agents/skills/draft_guide/SKILL.md +++ b/.agents/skills/draft_guide/SKILL.md @@ -41,7 +41,7 @@ The sidebar nav is defined in `src/sidebar.ts`, which organizes guides into topi ## Frontmatter description -One sentence, 50-160 characters, saying what the reader will build or accomplish, using the non-branded phrasing they would search for. +One to two sentences, 50-160 characters, saying what the reader will build or accomplish, using the non-branded phrasing they would search for. - ✅ `Set up Claude Code and run your first agentic coding session from the terminal.` - ❌ `A guide to using Claude Code with Warp.` diff --git a/.agents/skills/draft_procedural/SKILL.md b/.agents/skills/draft_procedural/SKILL.md index 1efb88556..b25871787 100644 --- a/.agents/skills/draft_procedural/SKILL.md +++ b/.agents/skills/draft_procedural/SKILL.md @@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **procedu ## Frontmatter description -One sentence, 50-160 characters, naming the task the reader will complete. Start with an imperative verb. +One to two sentences, 50-160 characters, naming the task the reader will complete. Start with an imperative verb. - ✅ `Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs.` - ❌ `This page explains the Slack integration setup process.` diff --git a/.agents/skills/draft_quickstart/SKILL.md b/.agents/skills/draft_quickstart/SKILL.md index 5e979da65..1f59d5167 100644 --- a/.agents/skills/draft_quickstart/SKILL.md +++ b/.agents/skills/draft_quickstart/SKILL.md @@ -21,7 +21,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **quickst ## Frontmatter description -One sentence, 50-160 characters, saying what the reader ends up with plus the time budget. Start with an imperative verb. +One to two sentences, 50-160 characters, saying what the reader ends up with plus the time budget. Start with an imperative verb. - ✅ `Install the Warp Agent CLI, log in, and run your first agent conversation in about five minutes.` - ❌ `Get started with the Warp Agent CLI.` diff --git a/.agents/skills/draft_reference/SKILL.md b/.agents/skills/draft_reference/SKILL.md index c1b33eed3..f4e4bd676 100644 --- a/.agents/skills/draft_reference/SKILL.md +++ b/.agents/skills/draft_reference/SKILL.md @@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **referen ## Frontmatter description -One sentence, 50-160 characters, saying what the reader can look up. Name the artifacts, not the genre. +One to two sentences, 50-160 characters, saying what the reader can look up. Name the artifacts, not the genre. - ✅ `Look up Warp Agent CLI flags, environment variables, slash commands, and keyboard shortcuts.` - ❌ `Reference documentation for the Warp Agent CLI.` diff --git a/.agents/skills/draft_troubleshooting/SKILL.md b/.agents/skills/draft_troubleshooting/SKILL.md index 2aea05c49..b853ba55b 100644 --- a/.agents/skills/draft_troubleshooting/SKILL.md +++ b/.agents/skills/draft_troubleshooting/SKILL.md @@ -13,7 +13,7 @@ Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **trouble ## Frontmatter description -One sentence, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting. +One to two sentences, 50-160 characters, naming the symptoms covered rather than the act of troubleshooting. - ✅ `Fix sign-in failures, failed conversation resumes, and update problems in the Warp Agent CLI.` - ❌ `Troubleshooting information for common problems.` diff --git a/.agents/templates/conceptual.md b/.agents/templates/conceptual.md index 85f8ae83c..233b05095 100644 --- a/.agents/templates/conceptual.md +++ b/.agents/templates/conceptual.md @@ -1,7 +1,7 @@ --- title: [Sentence case. Use "About [subject]" or a plain noun phrase naming the subject. Not "Understanding how X works". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: what the thing is and why it matters. Start with the + [One to two sentences, 50-160 characters: what the thing is and why it matters. Start with the subject, not "Learn about". Example: "Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] diff --git a/.agents/templates/faq.md b/.agents/templates/faq.md index 6e736542a..84d51ca7c 100644 --- a/.agents/templates/faq.md +++ b/.agents/templates/faq.md @@ -1,7 +1,7 @@ --- title: [Sentence case. Use "[Feature] FAQs" or "Frequently asked questions". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: name the topic area these questions cover. Not just + [One to two sentences, 50-160 characters: name the topic area these questions cover. Not just "Frequently asked questions". Example: "Answers to common questions about cloud agent billing, credits, and plan limits." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] diff --git a/.agents/templates/feature-doc.md b/.agents/templates/feature-doc.md index c8b678ac1..f315dc0a8 100644 --- a/.agents/templates/feature-doc.md +++ b/.agents/templates/feature-doc.md @@ -1,7 +1,7 @@ --- title: [Sentence case, task-based gerund when the page contains a procedure. Keep it general enough to cover the range of tasks on the page and agnostic about which option the reader picks: "Setting repository visibility", not "Making a private repository public". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: what the feature does and its primary benefit. Example: + [One to two sentences, 50-160 characters: what the feature does and its primary benefit. Example: "Control what the agent can do with permission cards, auto-approve, and execution profiles." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] --- diff --git a/.agents/templates/guide-page.md b/.agents/templates/guide-page.md index 312e5a855..ad7e2dcaf 100644 --- a/.agents/templates/guide-page.md +++ b/.agents/templates/guide-page.md @@ -1,7 +1,7 @@ --- title: [Sentence case, task-oriented, reading like a search query. Capture the non-branded query a developer would actually type: "How to set up Claude Code", not "How to set up Claude Code in Warp". Do not put "tutorial" or "guide" in the title. This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: what the reader will build or accomplish, in the + [One to two sentences, 50-160 characters: what the reader will build or accomplish, in the non-branded phrasing they would search for. Example: "Set up Claude Code and run your first agentic coding session from the terminal."] --- diff --git a/.agents/templates/procedural.md b/.agents/templates/procedural.md index f2a00f40a..91373f919 100644 --- a/.agents/templates/procedural.md +++ b/.agents/templates/procedural.md @@ -1,7 +1,7 @@ --- title: [Sentence case, beginning with a gerund that names the task. Example: "Configuring a self-hosted GitLab integration". Not "Self-hosted GitLab integration setup". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: the task the reader will complete. Start with an + [One to two sentences, 50-160 characters: the task the reader will complete. Start with an imperative verb, not "This page explains". Example: "Connect Slack to the Automation Platform so mentions and channel messages can trigger cloud agent runs." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] diff --git a/.agents/templates/quickstart.md b/.agents/templates/quickstart.md index 26dce20cd..2a562d6bd 100644 --- a/.agents/templates/quickstart.md +++ b/.agents/templates/quickstart.md @@ -1,7 +1,7 @@ --- title: [Sentence case, naming the feature. Use "Quickstart for [product]" or "[Feature] quickstart". Never a bare "Quickstart". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: what the reader ends up with, plus the time budget. + [One to two sentences, 50-160 characters: what the reader ends up with, plus the time budget. Start with an imperative verb, not "Learn how to" or "Get started with". Example: "Install the {{WARP_AGENT_CLI}}, log in, and run your first agent conversation in about five minutes." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] diff --git a/.agents/templates/reference.md b/.agents/templates/reference.md index e484f747d..ea416b4a1 100644 --- a/.agents/templates/reference.md +++ b/.agents/templates/reference.md @@ -1,7 +1,7 @@ --- title: [Sentence case. A noun phrase naming what can be looked up. Break up stacked nouns with prepositions: "Keyboard shortcuts for the code editor", not "Code editor keyboard shortcut reference". Never a bare "Overview" or "Reference". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: what the reader can look up here. Name the artifacts — + [One to two sentences, 50-160 characters: what the reader can look up here. Name the artifacts — flags, endpoints, shortcuts — not the genre. Example: "Look up {{WARP_AGENT_CLI}} flags, environment variables, slash commands, and keyboard shortcuts." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] diff --git a/.agents/templates/troubleshooting.md b/.agents/templates/troubleshooting.md index cb24d3bf6..5cd38d4a7 100644 --- a/.agents/templates/troubleshooting.md +++ b/.agents/templates/troubleshooting.md @@ -1,7 +1,7 @@ --- title: [Sentence case. Use "Troubleshooting [feature]" or "Known issues with [feature]". This renders as the page H1 — do not add an H1 in the body.] description: >- - [One sentence, 50-160 characters: name the symptoms covered, not the act of + [One to two sentences, 50-160 characters: name the symptoms covered, not the act of troubleshooting. Example: "Fix sign-in failures, failed conversation resumes, and update problems in the {{WARP_AGENT_CLI}}." Use {{TOKEN}} syntax for product names in src/data/vars.ts.] diff --git a/AGENTS.md b/AGENTS.md index ca429e297..21a46fbcf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -165,7 +165,7 @@ Every page must include YAML frontmatter with a `description` field. ```yaml --- description: >- - One sentence, 50-160 characters, stating what the reader gets from this page. + One to two sentences, 50-160 characters, stating what the reader gets from this page. --- ``` @@ -175,7 +175,7 @@ The `description` field is the meta description in search results and the snippe #### Description rules These apply to every page, regardless of content type. -- **One sentence, 50-160 characters.** Search engines truncate past roughly 160. Two sentences almost always overshoot the budget, so prefer one that earns its length. +- **One to two sentences, 50-160 characters.** Search engines truncate past roughly 160. Prefer one sentence when it earns its length; use a second only when both stay within budget and add real clarity, not padding. - **Cut filler openers.** "Learn about," "This page covers," "A guide to," and "Documentation for" spend characters without adding meaning. Start with the verb or the subject instead. - **Describe what the reader gets, not what the page is.** "This page explains X" is always weaker than explaining X. - **Lead with the primary keyword** when it reads naturally, ideally within the first few words. @@ -957,7 +957,7 @@ Add the key-value pair to `src/data/vars.ts` only. Both Option A (TypeScript imp All documentation should be written with search discoverability in mind — both for traditional search engines (Google) and AI engines (ChatGPT, Gemini, Perplexity, Copilot). ### Frontmatter descriptions -- Every page must have a `description` in frontmatter. Write it as a standalone summary (one sentence, 50-160 characters) that includes the primary keyword naturally. +- Every page must have a `description` in frontmatter. Write it as a standalone summary (one to two sentences, 50-160 characters) that includes the primary keyword naturally. - Descriptions appear in search results and AI citations. Write for humans, but include the key terms a developer would search for. - For the full rules and per-content-type patterns with examples, see [Frontmatter](#frontmatter) under Content structure. That section is the source of truth. @@ -977,7 +977,7 @@ Before publishing any documentation, verify: - [ ] The change passed `.agents/references/docs-worthiness-criteria.md` — the full gate with recorded evidence for automated runs, Gate 0 (shipped and public) for human-requested pages - [ ] A content design plan exists per `.agents/references/content-design-plan.md` and appears in the PR body - [ ] An existing page was updated rather than a new page created, unless a new page is genuinely justified -- [ ] Frontmatter includes a one-sentence description (50-160 chars) written as a standalone summary, with no filler opener +- [ ] Frontmatter includes a one-to-two-sentence description (50-160 chars) written as a standalone summary, with no filler opener - [ ] Content type is identified and the page follows the structure for that type (see `.agents/templates/`) - [ ] The title follows the convention for its content type (see "Titles by content type") - [ ] No quickstart or tutorial content is folded into a combined feature page