diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 41fccc5a..01902da0 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.agents/skills/draft_docs/SKILL.md @@ -88,11 +88,14 @@ These rules are frequently violated by agents. Apply them carefully during draft - **Product name variables** — For any product name in `src/data/vars.ts`, use the variable instead of the hardcoded string. Add `import { VARS } from '@data/vars';` immediately after the frontmatter closing `---`. Use `{VARS.KEY}` in MDX prose (e.g. `{VARS.WARP_AGENT_CLI}` not "Oz CLI"). Use `{{TOKEN}}` directly in frontmatter YAML values (e.g. `title: "{{WARP_AGENT_CLI}} reference"`). Key vars: `WARP_AGENT_CLI`, `WARP_AUTOMATION_PLATFORM`, `WEB_APP`, `WEB_APP_URL`, `DASHBOARD`, `AGENT_MODE`, `WARP_DRIVE`. See `src/data/vars.ts` for the full list. - **Sentence case for all headings (H1–H4)** — Capitalize only the first word and proper feature names. ✅ `## How it works` ❌ `## How It Works` -- **Descriptive, specific headings** — Beyond correct case, a heading should name the specific topic so readers and agents can scan the page and extract a self-contained answer. ✅ `## How key type affects billing and GitHub access` ❌ `## More details` -- **Bold + dash format for list items** — `* **Term** - Description`, not `* Term: Description` +- **Descriptive, specific headings** — Beyond correct case, a heading should name the specific topic so readers and agents can scan the page and extract a self-contained answer. Prefer the concrete object or outcome over vague section labels. ✅ `## How key type affects billing and GitHub access` / `## Configuring Workload Identity Federation` ❌ `## More details` / `## Overview` / `## Additional information` / `## Other` +- **Frontmatter `description` is a standalone search summary** — 1–2 sentences, roughly 50–160 characters when practical, that state the user benefit and primary keywords. It must make sense out of context (search result or AI citation). ✅ `description: Environments keep cloud agents on a consistent toolchain across every trigger.` ❌ `description: This page describes environments.` ❌ a description that only repeats the title with no benefit +- **Bold + dash format for list items** — `* **Term** - Description`, not `* Term: Description` and not `* Term — Description` (use a hyphen-minus + spaces around the dash separator after the bold term) +- **Unordered list marker is `*`** — Match the templates and existing docs. Use `* **Term** - Description` for feature/concept bullets. Reserve `-` only when you are inside a nested list that already uses `*` at the parent level, or when a numbered procedure is required (`1.`). ✅ `* **Codebase Context** - Warp indexes your Git-tracked codebase` ❌ `- **Codebase Context** - ...` as the top-level marker on a new page - **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` `` +- **Descriptive link text and Related pages** — Never use "here", "this page", or a bare URL as link text. On every new page, include a `## Related pages` section (or type-equivalent such as quickstart `## Next steps`) with at least one internal link whose anchor names the destination topic. ✅ `Learn more about [Codebase Context](/code/codebase-context/)` ❌ `Click [here](/code/codebase-context/)` ❌ ending a new feature page with no cross-links ### 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. @@ -115,12 +118,14 @@ Skip steps 1–3 in local/interactive sessions. ### 9. Review against checklist Before presenting the draft, verify against the quality checklist in `AGENTS.md`: -- [ ] Frontmatter includes clear description written as a standalone summary +- [ ] Frontmatter includes clear description written as a standalone summary (benefit + keywords; not "This page describes...") - [ ] Content follows the structure for its content type - [ ] Terminology matches the glossary (`.agents/references/terminology.md`) - [ ] Headers use sentence case (with proper feature name capitalization) -- [ ] Lists use bold term + dash + explanation format -- [ ] Cross-references to related features are included +- [ ] Headers name a specific topic (not bare Overview / More details / Other) +- [ ] Lists use `*` markers with bold term + hyphen dash + explanation format +- [ ] Cross-references to related features are included (`## Related pages` or type-equivalent Next steps) +- [ ] Link text names the destination topic (not "here" / "this page" / raw URLs) - [ ] Instructions include expected outcomes - [ ] Procedures are scannable: dense sections are split into numbered steps, short bullets, or concise subsections - [ ] UI surfaces and product terms use canonical names from `.agents/references/terminology.md` diff --git a/.agents/templates/conceptual.md b/.agents/templates/conceptual.md index 99803050..41c2c936 100644 --- a/.agents/templates/conceptual.md +++ b/.agents/templates/conceptual.md @@ -3,7 +3,8 @@ title: [Feature or concept name — sentence case. Title convention: noun or "Ab Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] description: >- [1-2 sentences: what the concept/feature is + why it matters. - Write as a standalone summary for search results. Lead with user benefit. + Write as a standalone summary for search results (benefit + keywords). + Do NOT write "This page describes..." or only restate the title. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. @@ -13,10 +14,10 @@ See AGENTS.md → Content variables for the full variable list and usage rules.] [Opening paragraph: What this feature/concept is and its primary benefit. 1-3 sentences. Lead with what the user gains from understanding this.] -## [Key concepts or components — sentence case. Rename to match the subject] +## [Key concepts or components — sentence case, specific to the subject. Not "Overview" or "More details"] [Explain the main ideas, components, or building blocks the reader needs -to understand. Use bulleted lists with bold term + dash + description.] +to understand. Use `*` bulleted lists with bold term + hyphen + description.] * **Concept A** - What it is and why it matters. * **Concept B** - What it is and why it matters. @@ -37,8 +38,9 @@ Help the reader decide if this is the right tool for their situation.] ## Related pages -[Cross-references to related features, procedural guides, and deeper references. -Use descriptive link text.] +[Required on new conceptual pages. Cross-references to related features, +procedural guides, and deeper references. +Use descriptive link text that names the destination — not "here" or "this page".] * [Related feature](path/to/page.md) * [How to configure X](path/to/procedural-page.md) diff --git a/.agents/templates/reference.md b/.agents/templates/reference.md index 86205039..8295f648 100644 --- a/.agents/templates/reference.md +++ b/.agents/templates/reference.md @@ -1,19 +1,21 @@ --- description: >- [1-2 sentences: what is documented and how to use this reference. + Standalone search summary: name the surface and the job-to-be-done. Example: "Use the {{WARP_AGENT_CLI}} to run, configure, and manage agents from the terminal." + Do NOT write "This page describes..." or only restate the title. Use {{TOKEN}} syntax for any product names in src/data/vars.ts.] --- [VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below. `import { VARS } from '@data/vars';` See AGENTS.md → Content variables for the full variable list and usage rules.] -# [Title — sentence case. Title convention: noun describing contents, e.g., "CLI commands", "Keyboard shortcuts"] +# [Title — sentence case. Title convention: noun describing contents, e.g., "CLI commands", "Keyboard shortcuts". Not bare "Overview" or "Reference".] [Brief intro: what this reference covers and how to use it. 1-2 sentences. This is for lookup, not learning.] -## [Section name — sentence case. e.g., "Installing the CLI", "Authentication"] +## [Section name — sentence case and specific. e.g., "Installing the CLI", "Authentication". Not "More details".] [Introductory sentence or conceptual context for this section.] @@ -26,7 +28,8 @@ For commands/endpoints: name → syntax → description → flags/params → exa For settings/options: name → type → default → description Use H2 for major sections, H3 for individual entries. -Use tables for multiple parameters, lists for single elements.] +Use tables for multiple parameters, lists for single elements. +For unordered bullets, use `*` markers (not `-`) and keep flag lists parallel.] ### `command-name` @@ -51,3 +54,11 @@ command-name --flag-name value [Repeat the same structure for every entry. Alphabetize entries where ordering doesn't matter.] + +## Related pages + +[Include on new reference pages when a conceptual or procedural companion exists. +Use descriptive link text that names the destination topic.] + +* [Conceptual overview](path/to/conceptual.md) +* [Setup guide](path/to/procedural.md)