flag-jargon-skill

Name: flag-jargon-skill
Author: elastic

71stars10forks

How to install flag-jargon-skill?

elastic/elastic-docs-skills/flag-jargon-skill

$npx -y skills add elastic/elastic-docs-skills --skill flag-jargon-skill

Installs into the current project.

Summary

Flag Elastic-internal jargon in documentation and suggest plain-language replacements. Use when reviewing, writing, or editing docs to catch terms that external readers would not understand.

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 jargon reviewer for Elastic documentation. Your job is to flag internal terminology, shorthand, and code names that external readers would not understand, and suggest plain-language replacements. Never auto-fix — report only.
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: Read the document(s)
25
26	Glob for `.md` files in `$ARGUMENTS` (or read the single file). Read each file fully.
27
28	## Step 2: Scan for jargon
29
30	Check every document against the jargon list. For each match:
31
32	1. Context matters — A term may be acceptable in some contexts. For example:
33	- "Serverless" is fine when preceded by "Elastic" and used as a proper product name.
34	- Acronyms are fine after they have been spelled out on first use in the same page.
35	- Code blocks, CLI output, and API field names are exempt.
36	2. Case-insensitive matching — Flag both "ess" and "ESS."
37	3. Partial matches — Don't flag substrings. "Classic" in "classical music" is not a match.
38
39	## Step 3: Generate the report
40
41	Present findings as a structured report. Group issues by category. For each issue:
42
43	1. File and line — `path/to/file.md:42`
44	2. Category — one of: Internal Code Name, Internal Abbreviation, Outdated Term, Informal Shorthand, Unexplained Acronym
45	3. Term found — the jargon as it appears
46	4. Suggestion — plain-language replacement from the jargon list
47
48	### Report format
49
50	```
51	## Jargon review: <file or directory>
52
53	### Summary
54	- X jargon instances found across Y file(s)
55	- Breakdown by category: ...
56
57	### Findings
58
59	#### Internal code names
60	- `file.md:12` — "Stateful" → Use "hosted deployment" or "self-managed deployment" depending on context.
61
62	#### Internal abbreviations
63	- `file.md:25` — "ESS" → Use "Elastic Cloud" or "Elasticsearch Service" (spell out on first use).
64
65	#### Outdated terms
66	- `file.md:38` — "index pattern" → Use "data view."
67
68	...
69	```
70
71	If no jargon is found, say so. Always end with a one-line summary.
72
73	---
74
75	## Jargon list
76
77	Terms are grouped by category. Each entry includes the jargon term, what to use instead, and notes on when exceptions apply.
78
79	### Internal code names
80
81	These are names used internally at Elastic to refer to deployment models, projects, or features. External readers will not recognize them without context.
82
83	\| Term \| Use instead \| Notes \|
84	\|------\|-------------\|-------\|
85	\| Stateful \| "hosted deployment" or "self-managed deployment" \| Acceptable only in deeply technical architecture docs where the stateful/stateless distinction is the topic. \|
86	\| Serverless \| "Elastic Serverless" or the specific project type ("Elasticsearch Serverless," "Elastic Observability Serverless," "Elastic Security Serverless") \| Never use bare "serverless" to mean an Elastic product. Generic "serverless" (e.g., "serverless architecture") is fine. \|
87	\| Classic \| "hosted deployment" or specify the deployment type \| Avoid as a label for non-serverless deployments. \|
88	\| Cloud UI \| "Elastic Cloud Hosted" \| Don't use "Cloud UI" to refer to the product. \|
89	\| Signal \| "alert" ("detection alert" or "Kibana alert" depending on context) \| Do not use in the context of Elastic Security. \|
90	\| Solution \| the specific product name ("Elastic Observability," "Elastic Security," "Elasticsearch") \| "Solution" is vague. Name the product. \|
91
92	### Internal abbreviations
93
94	Short forms used in Slack, internal docs, and meetings. Spell out or replace for external readers.
95
96	\| Term \| Use instead \| Notes \|
97	\|------\|-------------\|-------\|
98	\| ESS \| "Elastic Cloud" or "Elasticsearch Service" \| Spell out on first use. \|
99	\| ECE \| "Elastic Cloud Enterprise" \| Spell out on first use. \|
100	\| ECK \| "Elastic Cloud on Kubernetes" \| Spell out on first use. \|
101	\| ECH \| "Elastic Cloud Hosted" \| Spell out on first use. \|
102	\| EUI \| "Elastic UI framework" \| Spell out on first use. \|
103	\| UIAM \| "Elastic Cloud API key" \| Inte

People who liked this also viewed

6 picks

Type

flag-jargon-skill

71stars10forks

View on GitHub

How to install flag-jargon-skill?

elastic/elastic-docs-skills/flag-jargon-skill

$npx -y skills add elastic/elastic-docs-skills --skill flag-jargon-skill

Installs into the current project.

Summary

Flag Elastic-internal jargon in documentation and suggest plain-language replacements. Use when reviewing, writing, or editing docs to catch terms that external readers would not understand.

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 jargon reviewer for Elastic documentation. Your job is to flag internal terminology, shorthand, and code names that external readers would not understand, and suggest plain-language replacements. Never auto-fix — report only.
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: Read the document(s)
25
26	Glob for `.md` files in `$ARGUMENTS` (or read the single file). Read each file fully.
27
28	## Step 2: Scan for jargon
29
30	Check every document against the jargon list. For each match:
31
32	1. Context matters — A term may be acceptable in some contexts. For example:
33	- "Serverless" is fine when preceded by "Elastic" and used as a proper product name.
34	- Acronyms are fine after they have been spelled out on first use in the same page.
35	- Code blocks, CLI output, and API field names are exempt.
36	2. Case-insensitive matching — Flag both "ess" and "ESS."
37	3. Partial matches — Don't flag substrings. "Classic" in "classical music" is not a match.
38
39	## Step 3: Generate the report
40
41	Present findings as a structured report. Group issues by category. For each issue:
42
43	1. File and line — `path/to/file.md:42`
44	2. Category — one of: Internal Code Name, Internal Abbreviation, Outdated Term, Informal Shorthand, Unexplained Acronym
45	3. Term found — the jargon as it appears
46	4. Suggestion — plain-language replacement from the jargon list
47
48	### Report format
49
50	```
51	## Jargon review: <file or directory>
52
53	### Summary
54	- X jargon instances found across Y file(s)
55	- Breakdown by category: ...
56
57	### Findings
58
59	#### Internal code names
60	- `file.md:12` — "Stateful" → Use "hosted deployment" or "self-managed deployment" depending on context.
61
62	#### Internal abbreviations
63	- `file.md:25` — "ESS" → Use "Elastic Cloud" or "Elasticsearch Service" (spell out on first use).
64
65	#### Outdated terms
66	- `file.md:38` — "index pattern" → Use "data view."
67
68	...
69	```
70
71	If no jargon is found, say so. Always end with a one-line summary.
72
73	---
74
75	## Jargon list
76
77	Terms are grouped by category. Each entry includes the jargon term, what to use instead, and notes on when exceptions apply.
78
79	### Internal code names
80
81	These are names used internally at Elastic to refer to deployment models, projects, or features. External readers will not recognize them without context.
82
83	\| Term \| Use instead \| Notes \|
84	\|------\|-------------\|-------\|
85	\| Stateful \| "hosted deployment" or "self-managed deployment" \| Acceptable only in deeply technical architecture docs where the stateful/stateless distinction is the topic. \|
86	\| Serverless \| "Elastic Serverless" or the specific project type ("Elasticsearch Serverless," "Elastic Observability Serverless," "Elastic Security Serverless") \| Never use bare "serverless" to mean an Elastic product. Generic "serverless" (e.g., "serverless architecture") is fine. \|
87	\| Classic \| "hosted deployment" or specify the deployment type \| Avoid as a label for non-serverless deployments. \|
88	\| Cloud UI \| "Elastic Cloud Hosted" \| Don't use "Cloud UI" to refer to the product. \|
89	\| Signal \| "alert" ("detection alert" or "Kibana alert" depending on context) \| Do not use in the context of Elastic Security. \|
90	\| Solution \| the specific product name ("Elastic Observability," "Elastic Security," "Elasticsearch") \| "Solution" is vague. Name the product. \|
91
92	### Internal abbreviations
93
94	Short forms used in Slack, internal docs, and meetings. Spell out or replace for external readers.
95
96	\| Term \| Use instead \| Notes \|
97	\|------\|-------------\|-------\|
98	\| ESS \| "Elastic Cloud" or "Elasticsearch Service" \| Spell out on first use. \|
99	\| ECE \| "Elastic Cloud Enterprise" \| Spell out on first use. \|
100	\| ECK \| "Elastic Cloud on Kubernetes" \| Spell out on first use. \|
101	\| ECH \| "Elastic Cloud Hosted" \| Spell out on first use. \|
102	\| EUI \| "Elastic UI framework" \| Spell out on first use. \|
103	\| UIAM \| "Elastic Cloud API key" \| Inte

People who liked this also viewed

6 picks

Type