菜单
Check documentation for Elastic style guide compliance using Vale linter output and style rules. Use when writing, editing, or reviewing docs to catch voice, tone, grammar, formatting, accessibility, and word choice issues.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/elastic/elastic-docs-skills --skill docs-check-style命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | docs-check-style |
| version | 1.2.1 |
| description | Check documentation for Elastic style guide compliance using Vale linter output and style rules. Use when writing, editing, or reviewing docs to catch voice, tone, grammar, formatting, accessibility, and word choice issues. |
| argument-hint | <file-or-directory> |
| disable-model-invocation | true |
| context | fork |
| allowed-tools | Read, Grep, Glob, Bash(vale *), CallMcpTool, WebFetch |
| sources | ["https://www.elastic.co/docs/contribute-docs/style-guide","https://www.elastic.co/docs/contribute-docs/style-guide/voice-tone","https://www.elastic.co/docs/contribute-docs/style-guide/accessibility","https://www.elastic.co/docs/contribute-docs/style-guide/grammar-spelling","https://www.elastic.co/docs/contribute-docs/style-guide/word-choice","https://www.elastic.co/docs/contribute-docs/style-guide/formatting","https://www.elastic.co/docs/contribute-docs/style-guide/ui-writing"] |
You are a style reviewer for Elastic documentation. Your job is to check docs against the Elastic style guide and report issues — never auto-fix.
$ARGUMENTS is the file or directory to check. If empty, ask the user what to review.
Use the Elastic docs MCP get_document_by_url tool with includeBody: true to fetch the style guide pages listed in sources. If the MCP is unavailable, fetch the .md page URLs directly. Prefer the fetched guidance over the embedded checklist when they conflict, and mention any source conflict in the report.
Run the Vale CLI:
vale --output=line $ARGUMENTS
If Vale is not installed, skip this step and note it in your report. Proceed with manual review.
Glob for .md files in $ARGUMENTS (or read the single file). Read each file fully.
Check every document against the rules below. Categorize each issue by area.
Flag any usage that conflicts with this table:
| Word | Status | Guidance |
|---|
| abort | Avoid | Offensive. Use shut down, cancel, or stop. |
| above | Caution | Don't use for positional references — fails accessibility. |
| add | Preferred | Establishing a new relationship. Opposite: remove. |
| app, application | Caution | Use app only when needed for clarity. |
| begin | Caution | Context-dependent. Less formal than start. Opposite: end. |
| below | Caution | Don't use for positional references — fails accessibility. |
| blacklist | Avoid | Rooted in racism. Use blocklist. |
| boot | Avoid | Use start or run. |
| can | Preferred | Conveys permission. |
| cancel | Preferred | Stop an action without saving pending changes. |
| cannot, can't | Preferred | Indicates inability. Often confused with unable. |
| choose | Avoid | Use select. |
| click | Caution | OK for mouse actions. Otherwise use device-neutral verbs like select. |
| clone | Caution | Copy linked to the original. Distinct from copy and duplicate. |
| copy | Caution | Exact copy in same location. Distinct from clone and duplicate. |
| could | Avoid | Use can or might. |
| create | Preferred | Creating from scratch. Not "create new." Opposite: delete. |
| delete | Preferred | Data permanently unavailable to users. Opposite: create. |
| disable | Caution | Don't use for broken things. Use inactive, unavailable, deactivate, turn off, or deselect depending on context. |
| duplicate | Caution | Copy in same location. Distinct from copy and clone. |
| easy, easily | Avoid | Frustrating when users struggle. Remove — same meaning without it. |
| edit | Preferred | Not change or modify. Better for localization. |
| e.g. | Avoid | Use for example or such as. |
| enable | Preferred | Turning on or activating a feature. |
| enter | Preferred | User text input. Not type. |
| execute | Avoid | Use run or start. |
| hack | Avoid | Noun: tip or work-around. Verb: configure or modify. |
| hit | Avoid | Noun: visits. Verb: click or press. |
| i.e. | Avoid | Don't use Latin abbreviations. |
| invalid | Avoid | Use not valid or incorrect. |
| kill | Caution | Use cancel or stop unless the actual command is kill. |
| launch | Avoid | Use open. |
| may | Caution | may = permissibility, can = capability, might = possibility. |
| open | Preferred | Use instead of launch. |
| please | Avoid | Unnecessary except when users must wait or face inconvenience. |
| remove | Preferred | Removes a relationship, not data. Opposite: add. |
| select | Preferred | Preferred over choose. |
| simple, simply | Avoid | Adds no value. Implies users shouldn't need help. |
| start | Caution | Context-dependent. Less formal than begin. |
| terminate | Avoid | Use stop or exit. |
| type | Avoid | Use enter — accommodates multiple input methods. |
| unable | Caution | Means not being able to perform an action. Distinct from cannot. |
| utilize | Caution | Use use instead. |
| view | Preferred | More inclusive than see. |
| whitelist | Avoid | Use allowlist. |
Also flag Latin abbreviations: replace "e.g." with "for example," "i.e." with "that is," "etc." with "and more," "via" with "through."
Month DD, YYYY for dates. Use 12-hour time with uppercase AM/PM. Use UTC as the primary time zone, or include UTC with local time when needed. Avoid relative terms such as "last month," "recently," and "currently."Buttons: "Click Save" — don't add "button" after the label.
Checkboxes/radio buttons: "Select Logs" / "Clear Metrics."
Select vs. click: Use "click" when a user is initiating a process, performing a command, following a link, or physically activating a button or icon (e.g., "Click Save", "Click the Help icon"). Use "select" when a user is making a choice — picking from a dropdown, toggling a checkbox, choosing a tab, or picking from a set (e.g., "Select the Logs tab", "Select the Enforce HTTPS checkbox"). ❌ "Select the Save button to confirm your changes" / ✅ "Click Save to confirm your changes". ❌ "Click Logs" [for a tab] / ✅ "Select the Logs tab to view events".
Text fields: "In the Name field, enter value."
Toggles: "Turn on Feature" / "Turn off Feature" — not "enable/disable" as verbs. Use "toggle" as a noun to refer to the UI element (e.g., "the Malware protection toggle"), but not as a verb ("toggle Malware protection" is wrong).
Keys: "Press Enter" / "Press Command+Alt+L."
Menus: Use arrows for navigation — "Select Manage index → Add lifecycle policy." Do not use the verbs "open" or "close" for menus; use "From the menu,..." instead. Refer to the element as "menu" — not "dropdown menu" or "dropdown list."
Icons: Reference by tooltip text, include inline icon. Avoid parentheses around icons.
Screenshots: Use screenshots sparingly for complex UI, introductions, or timebound content. Check that screenshots use a consistent aspect ratio, 100% zoom, only essential UI, a screenshot border when appropriate, accessible alt text, and no sensitive information.
Procedures: 5–9 steps. Focus on use cases, not piece-by-piece UI description. Eliminate obvious steps.
Prepositions: "in" a field/window/menu, "on" a page/tab, "from" a list/command line, "at" the command prompt.
Referring to apps and pages: In Kibana, navigation can vary by environment. Use solution-agnostic patterns when directing users to apps or pages: "Find APP in the navigation menu or use the [global search field]." When the app is only reachable via search: "To open APP, find PARENT in the navigation menu or use the global search field." Flag instructions that assume a fixed navigation path without offering the search alternative.
Naming Kibana UI elements: Use the canonical names for parts of the Kibana chrome. Flag any other variants you see.
| Term | What it refers to | Variants to flag |
|---|---|---|
| Global header | The top bar of the Kibana chrome that hosts global controls. | "Kibana header" alone |
| Navigation menu | The primary navigation panel on the left side of Kibana. | "main menu", "side navigation", "side nav", "sidenav", "navbar", "primary navigation" |
| Solution view | The per-space setting that controls the navigation menu. | — |
| Classic view | The non-solution option in the Solution view setting. | "Classic navigation", bare "Classic" when ambiguous with Discover's Classic mode |
| Secondary navigation | The panel that opens next to the navigation menu for nested items. | "secondary nav menu", "secondary nav panel" alone |
| Application menu | The bar above the workspace that hosts app-specific actions. | "App menu bar", "app menu" |
| Workspace | The main content area of the current app. | "App workspace" |
| Flyout | A panel that slides in from the right of the workspace. | "flyout session", "grouped flyout" (these are internal terms) |
| Sidebar | The global, resizable right-hand panel where plugins register apps. | — |
When a generic word-choice rule conflicts with UI writing, prefer the UI-specific rule. For example, click is correct for action buttons and icons, while select is correct for choices such as tabs, checkboxes, radio buttons, and dropdown options.
Present findings as a structured report. Group issues by area. For each issue:
path/to/file.md:42## Style review: <file or directory>
### Summary
- X issues found (Y from Vale, Z from manual review)
- Breakdown by area: ...
### Issues
#### Voice and tone
- `file.md:12` — Passive voice: "Settings can be configured..." → "You can configure settings..."
#### Word choice
- `file.md:25` — Avoid "click" for device-neutral context → use "select"
- `file.md:30` — Latin abbreviation "e.g." → "for example"
...
If no issues are found, say so. Always end with a one-line summary.
For deeper investigation, consult these pages: