docs-check-style

Name: docs-check-style
Author: elastic

71stars10forks

How to install docs-check-style?

elastic/elastic-docs-skills/docs-check-style

$npx -y skills add elastic/elastic-docs-skills --skill docs-check-style

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
2	or more contributor license agreements. See the NOTICE file distributed with
3	this work for additional information regarding copyright
4	ownership. Elasticsearch B.V. licenses this file to you under
5	the Apache License, Version 2.0 (the "License"); you may
6	not use this file except in compliance with the License.
7	You may obtain a copy of the License at
8
9	http://www.apache.org/licenses/LICENSE-2.0
10
11	Unless required by applicable law or agreed to in writing,
12	software distributed under the License is distributed on an
13	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14	KIND, either express or implied. See the License for the
15	specific language governing permissions and limitations
16	under the License. -->
17
18	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.
19
20	## Inputs
21
22	`$ARGUMENTS` is the file or directory to check. If empty, ask the user what to review.
23
24	## Step 1: Refresh style guidance
25
26	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.
27
28	## Step 2: Run Vale
29
30	Run the Vale CLI:
31
32	```
33	vale --output=line $ARGUMENTS
34	```
35
36	If Vale is not installed, skip this step and note it in your report. Proceed with manual review.
37
38	## Step 3: Read the document(s)
39
40	Glob for `.md` files in `$ARGUMENTS` (or read the single file). Read each file fully.
41
42	## Step 4: Review against style rules
43
44	Check every document against the rules below. Categorize each issue by area.
45
46	---
47
48	### Voice and tone
49
50	- Active voice: Prefer active over passive. Passive is acceptable only when active sounds awkward.
51	- Present tense: Write in present tense. Avoid "will," "would," "should," "could," "currently," "now."
52	- Second person: Use "you/your/yours." Never use "I/me/my." Use "we" sparingly ("we recommend" is OK).
53	- No "please": Remove "please" from instructions. Exception: when users must wait or face inconvenience.
54	- Contractions: Use them for conversational tone. Don't mix contractions with spelled-out equivalents in the same context. Avoid ambiguous contractions ("there'd," "it'll," "they'd").
55	- Concise sentences: Limit conjunctions to two per sentence. Prefer simple present over gerunds in prose.
56	- Informational tone: Most docs should be direct, neutral, and scannable. Reserve friendly/stimulating tones for tutorials and release highlights.
57
58	### Word choice
59
60	Flag any usage that conflicts with this table:
61
62	\| Word \| Status \| Guidance \|
63	\|------\|--------\|----------\|
64	\| abort \| Avoid \| Offensive. Use _shut down_, _cancel_, or _stop_. \|
65	\| above \| Caution \| Don't use for positional references — fails accessibility. \|
66	\| add \| Preferred \| Establishing a new relationship. Opposite: _remove_. \|
67	\| app, application \| Caution \| Use _app_ only when needed for clarity. \|
68	\| begin \| Caution \| Context-dependent. Less formal than _start_. Opposite: _end_. \|
69	\| below \| Caution \| Don't use for positional references — fails accessibility. \|
70	\| blacklist \| Avoid \| Rooted in racism. Use _blocklist_. \|
71	\| boot \| Avoid \| Use _start_ or _run_. \|
72	\| can \| Preferred \| Conveys permission. \|
73	\| cancel \| Preferred \| Stop an action without saving pending changes. \|
74	\| cannot, can't \| Preferred \| Indicates inability. Often confused with _unable_. \|
75	\| choose \| Avoid \| Use _select_. \|
76	\| click \| Caution \| OK for mouse actions. Otherwise use device-neutral verbs like _select_. \|
77	\| clone \| Caution \| Copy linked to the original. Distinct from _copy_ and _duplicate_. \|
78	\| copy \| Caution \| Exact copy in same location. Distinct from _clone_ and _duplicate_. \|
79	\| could \| Avoid \| Use _can_ or _might_. \|
80	\| create \| Preferred \| Creating from scratch. Not "create new." Opposite: _delete_. \|
81	\| delete \| Preferred \| Data permanently unavailable to users. Opposite: _c

People who liked this also viewed

6 picks

Type

docs-check-style

71stars10forks

View on GitHub

How to install docs-check-style?

elastic/elastic-docs-skills/docs-check-style

$npx -y skills add elastic/elastic-docs-skills --skill docs-check-style

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
2	or more contributor license agreements. See the NOTICE file distributed with
3	this work for additional information regarding copyright
4	ownership. Elasticsearch B.V. licenses this file to you under
5	the Apache License, Version 2.0 (the "License"); you may
6	not use this file except in compliance with the License.
7	You may obtain a copy of the License at
8
9	http://www.apache.org/licenses/LICENSE-2.0
10
11	Unless required by applicable law or agreed to in writing,
12	software distributed under the License is distributed on an
13	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14	KIND, either express or implied. See the License for the
15	specific language governing permissions and limitations
16	under the License. -->
17
18	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.
19
20	## Inputs
21
22	`$ARGUMENTS` is the file or directory to check. If empty, ask the user what to review.
23
24	## Step 1: Refresh style guidance
25
26	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.
27
28	## Step 2: Run Vale
29
30	Run the Vale CLI:
31
32	```
33	vale --output=line $ARGUMENTS
34	```
35
36	If Vale is not installed, skip this step and note it in your report. Proceed with manual review.
37
38	## Step 3: Read the document(s)
39
40	Glob for `.md` files in `$ARGUMENTS` (or read the single file). Read each file fully.
41
42	## Step 4: Review against style rules
43
44	Check every document against the rules below. Categorize each issue by area.
45
46	---
47
48	### Voice and tone
49
50	- Active voice: Prefer active over passive. Passive is acceptable only when active sounds awkward.
51	- Present tense: Write in present tense. Avoid "will," "would," "should," "could," "currently," "now."
52	- Second person: Use "you/your/yours." Never use "I/me/my." Use "we" sparingly ("we recommend" is OK).
53	- No "please": Remove "please" from instructions. Exception: when users must wait or face inconvenience.
54	- Contractions: Use them for conversational tone. Don't mix contractions with spelled-out equivalents in the same context. Avoid ambiguous contractions ("there'd," "it'll," "they'd").
55	- Concise sentences: Limit conjunctions to two per sentence. Prefer simple present over gerunds in prose.
56	- Informational tone: Most docs should be direct, neutral, and scannable. Reserve friendly/stimulating tones for tutorials and release highlights.
57
58	### Word choice
59
60	Flag any usage that conflicts with this table:
61
62	\| Word \| Status \| Guidance \|
63	\|------\|--------\|----------\|
64	\| abort \| Avoid \| Offensive. Use _shut down_, _cancel_, or _stop_. \|
65	\| above \| Caution \| Don't use for positional references — fails accessibility. \|
66	\| add \| Preferred \| Establishing a new relationship. Opposite: _remove_. \|
67	\| app, application \| Caution \| Use _app_ only when needed for clarity. \|
68	\| begin \| Caution \| Context-dependent. Less formal than _start_. Opposite: _end_. \|
69	\| below \| Caution \| Don't use for positional references — fails accessibility. \|
70	\| blacklist \| Avoid \| Rooted in racism. Use _blocklist_. \|
71	\| boot \| Avoid \| Use _start_ or _run_. \|
72	\| can \| Preferred \| Conveys permission. \|
73	\| cancel \| Preferred \| Stop an action without saving pending changes. \|
74	\| cannot, can't \| Preferred \| Indicates inability. Often confused with _unable_. \|
75	\| choose \| Avoid \| Use _select_. \|
76	\| click \| Caution \| OK for mouse actions. Otherwise use device-neutral verbs like _select_. \|
77	\| clone \| Caution \| Copy linked to the original. Distinct from _copy_ and _duplicate_. \|
78	\| copy \| Caution \| Exact copy in same location. Distinct from _clone_ and _duplicate_. \|
79	\| could \| Avoid \| Use _can_ or _might_. \|
80	\| create \| Preferred \| Creating from scratch. Not "create new." Opposite: _delete_. \|
81	\| delete \| Preferred \| Data permanently unavailable to users. Opposite: _c

People who liked this also viewed

6 picks

Type