メニュー
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コマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Suggest improved text for changelog YAML files against current Elastic standards. Mirrors the pattern catalog from docs-review-changelog to provide consistent fixes. Includes type-title alignment, product/surface context for titles, description verb-tense (third-person present), and technical content assessment. Features repository-aware area validation and enhanced confidence scoring. Supports single files or directories. Fetches canonical guidance to stay in sync. Use after review identifies quality issues, or when drafting new changelogs.
Validate and assess the quality of Elastic changelog YAML files against current Elastic standards. Reports schema errors, content quality issues, systematic pattern violations, type-title alignment mismatches, missing product/surface context in titles, description verb-tense issues, and overly technical content that needs user-focused rewrites. Features repository-aware area validation. Fetches canonical guidance to stay in sync. Use when checking or reviewing changelog files before merging — pairs with docs-fix-changelog to get suggested fixes.
Validate and generate applies_to tags in Elastic documentation, including for cumulative docs across versions and deployment types. Use when writing new docs pages, reviewing existing pages for correct applies_to usage, deciding whether to preserve or replace existing version-scoped content, or when content changes lifecycle state (experimental, preview, beta, GA, deprecated, removed).
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: