page-opening-optimizer

Name: page-opening-optimizer
Author: elastic

71stars10forks

How to install page-opening-optimizer?

elastic/elastic-docs-skills/page-opening-optimizer

$npx -y skills add elastic/elastic-docs-skills --skill page-opening-optimizer

Installs into the current project.

Summary

Optimize the opening of an Elastic documentation page — H1 title, opening paragraph, and requirements section — following doc type conventions. Use when writing or improving page intros, optimizing titles for discoverability, adding requirements sections, or when the user asks to

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 page opening optimizer for Elastic documentation. Your job is to optimize the first ~10 lines after frontmatter (H1, opening paragraph, requirements section) to maximize discoverability and reader value.
19
20	## Inputs
21
22	`$ARGUMENTS` is a file path or directory. If a directory, process all `.md` files. If empty, ask the user what to optimize.
23
24	## Step 1: Classify the documentation type
25
26	Read the file and identify its type. This determines H1 style, opening tone, and whether to add requirements.
27
28	\| Type \| Characteristics \| H1 pattern \|
29	\|------\|----------------\|------------\|
30	\| Tutorial \| Learning-oriented, hands-on for beginners \| "Get started with [feature]" \|
31	\| How-to \| Goal-oriented task instructions \| "Configure [feature]", "Troubleshoot [problem]" \|
32	\| Reference \| Technical specifications \| "[Feature] settings", "[API] reference" \|
33	\| Explanation \| Conceptual overviews \| "How [feature] works" \|
34	\| Overview \| Parent pages with `children:` in `toc.yml` \| Feature name only \|
35
36	To detect overview pages, check `toc.yml` for entries with `children:` pointing to the file.
37
38	## Step 2: Optimize the H1 title
39
40	The H1 must be:
41
42	1. Discoverable — include the feature name and context (e.g., "in Kibana", "with ES\|QL")
43	2. Specific — clearly indicate what the page covers
44	3. Unique — no other page should share this title
45	4. Anchored — always include `[anchor-name]` in brackets
46
47	```markdown
48	# Configure data views in Kibana [configure-data-views]
49	```
50
51	If the H1 exceeds ~50 characters, add `navigation_title` to the frontmatter.
52
53	## Step 3: Write the opening paragraph
54
55	The opening paragraph (2-4 sentences) immediately follows the H1. It must NOT repeat the frontmatter `description`.
56
57	### By doc type
58
59	Tutorial — Define the feature, explain how it works, state what the tutorial covers:
60	```markdown
61	Elasticsearch Query Language ({{esql}}) makes it easier to explore your data
62	in Discover. {{esql}} uses a piped syntax to filter, transform, and aggregate
63	data. This tutorial walks you through querying sample data, from basic field
64	selection to complex filtering and visualization.
65	```
66
67	How-to — Define the feature, explain what it does, state the value:
68	```markdown
69	Pattern analysis in Discover helps you find patterns in unstructured log
70	messages by performing categorization analysis on text fields. It creates
71	categories based on message structures and displays their distribution,
72	making it easier to identify common patterns and focus on anomalous messages.
73	```
74
75	Reference — Define the subject, state its purpose:
76	```markdown
77	API keys provide secure, token-based authentication for applications accessing
78	{{product.elasticsearch}}. Use API keys instead of usernames and passwords when
79	integrating external applications.
80	```
81
82	Explanation — Establish context, state what concepts are covered:
83	```markdown
84	{{product.elasticsearch}} distributes search requests across multiple shards
85	and nodes. Understanding query and fetch phases helps you optimize search
86	performance and troubleshoot slow queries.
87	```
88
89	Overview — State what the feature is, its value, and key capabilities:
90	```markdown
91	Discover is the primary tool for exploring your data in {{product.kibana}}.
92	Search and filter documents, analyze field structures, visualize patterns, and
93	save your findings to reuse later or share with dashboards.
94	```
95
96	### Key principles
97
98	- Don't repeat the frontmatter `description`
99	- Don't have two consecutive paragraphs repeating

People who liked this also viewed

6 picks

Type

page-opening-optimizer

71stars10forks

View on GitHub

How to install page-opening-optimizer?

elastic/elastic-docs-skills/page-opening-optimizer

$npx -y skills add elastic/elastic-docs-skills --skill page-opening-optimizer

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 page opening optimizer for Elastic documentation. Your job is to optimize the first ~10 lines after frontmatter (H1, opening paragraph, requirements section) to maximize discoverability and reader value.
19
20	## Inputs
21
22	`$ARGUMENTS` is a file path or directory. If a directory, process all `.md` files. If empty, ask the user what to optimize.
23
24	## Step 1: Classify the documentation type
25
26	Read the file and identify its type. This determines H1 style, opening tone, and whether to add requirements.
27
28	\| Type \| Characteristics \| H1 pattern \|
29	\|------\|----------------\|------------\|
30	\| Tutorial \| Learning-oriented, hands-on for beginners \| "Get started with [feature]" \|
31	\| How-to \| Goal-oriented task instructions \| "Configure [feature]", "Troubleshoot [problem]" \|
32	\| Reference \| Technical specifications \| "[Feature] settings", "[API] reference" \|
33	\| Explanation \| Conceptual overviews \| "How [feature] works" \|
34	\| Overview \| Parent pages with `children:` in `toc.yml` \| Feature name only \|
35
36	To detect overview pages, check `toc.yml` for entries with `children:` pointing to the file.
37
38	## Step 2: Optimize the H1 title
39
40	The H1 must be:
41
42	1. Discoverable — include the feature name and context (e.g., "in Kibana", "with ES\|QL")
43	2. Specific — clearly indicate what the page covers
44	3. Unique — no other page should share this title
45	4. Anchored — always include `[anchor-name]` in brackets
46
47	```markdown
48	# Configure data views in Kibana [configure-data-views]
49	```
50
51	If the H1 exceeds ~50 characters, add `navigation_title` to the frontmatter.
52
53	## Step 3: Write the opening paragraph
54
55	The opening paragraph (2-4 sentences) immediately follows the H1. It must NOT repeat the frontmatter `description`.
56
57	### By doc type
58
59	Tutorial — Define the feature, explain how it works, state what the tutorial covers:
60	```markdown
61	Elasticsearch Query Language ({{esql}}) makes it easier to explore your data
62	in Discover. {{esql}} uses a piped syntax to filter, transform, and aggregate
63	data. This tutorial walks you through querying sample data, from basic field
64	selection to complex filtering and visualization.
65	```
66
67	How-to — Define the feature, explain what it does, state the value:
68	```markdown
69	Pattern analysis in Discover helps you find patterns in unstructured log
70	messages by performing categorization analysis on text fields. It creates
71	categories based on message structures and displays their distribution,
72	making it easier to identify common patterns and focus on anomalous messages.
73	```
74
75	Reference — Define the subject, state its purpose:
76	```markdown
77	API keys provide secure, token-based authentication for applications accessing
78	{{product.elasticsearch}}. Use API keys instead of usernames and passwords when
79	integrating external applications.
80	```
81
82	Explanation — Establish context, state what concepts are covered:
83	```markdown
84	{{product.elasticsearch}} distributes search requests across multiple shards
85	and nodes. Understanding query and fetch phases helps you optimize search
86	performance and troubleshoot slow queries.
87	```
88
89	Overview — State what the feature is, its value, and key capabilities:
90	```markdown
91	Discover is the primary tool for exploring your data in {{product.kibana}}.
92	Search and filter documents, analyze field structures, visualize patterns, and
93	save your findings to reuse later or share with dashboards.
94	```
95
96	### Key principles
97
98	- Don't repeat the frontmatter `description`
99	- Don't have two consecutive paragraphs repeating

People who liked this also viewed

6 picks

Type