Skip to content

Commit b00d3f9

Browse files
mbaldessarimbaldessari
authored
Merge pull request #650 from gaurav-nelson/ai_skills
AI skills for creating and fixing docs
2 parents 7ac8632 + 5ca88f0 commit b00d3f9

32 files changed

Lines changed: 2136 additions & 1 deletion

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,5 @@ Gemfile.lock
1717
.vale
1818
modules/.vale.ini
1919
.vale.ini
20+
.claude
21+
.cursor

‎.rulesync/skills/doc-create/SKILL.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
name: doc-create
3+
description: Create new documentation pages for the validatedpatterns.io site. Supports learn pages and pattern page sets. Generates AsciiDoc files with correct frontmatter, structure, and style-compliant content. Use this skill whenever the user wants to write, draft, scaffold, generate, or create new documentation pages — whether for learn content, patterns, tutorials, or guides. Triggers on requests like "create a new page", "write docs for", "scaffold a pattern", "add a learn page", "generate documentation", or any task involving new .adoc/.md content for the site, even if the user does not name this skill explicitly.
4+
argument-hint: <content-type> <topic-or-name>
5+
---
6+
7+
Create new documentation for the validatedpatterns.io Hugo site. Follow the workflow below precisely.
8+
9+
---
10+
11+
## Step 1: Resolve content type and gather inputs
12+
13+
- If `$ARGUMENTS` is empty, ask the user what content type (`learn` or `pattern`) and topic to create.
14+
- If `$ARGUMENTS` contains a content type and topic, use them directly.
15+
16+
### Learn pages
17+
18+
Collect:
19+
- **title** (required): Page title in sentence-style capitalization.
20+
- **parent menu** (optional): If this is a child page, the parent menu label (e.g. "Patterns quick start"). Leave empty for top-level learn pages.
21+
- **weight** (required): Sort order (10, 20, 30, ...).
22+
- **topic summary**: Brief description of what the page covers — used to generate content.
23+
24+
### Pattern page sets
25+
26+
Collect:
27+
- **pattern name** (required): Lowercase, dash-separated directory name (e.g. `my-new-pattern`).
28+
- **title** (required): Human-readable pattern title.
29+
- **date** (required): Publication date in `YYYY-MM-DD` format.
30+
- **summary** (required): One-sentence pattern description.
31+
- **tier** (required): `sandbox`, `tested`, or `maintained`.
32+
- **rh_products** (required): List of Red Hat products used.
33+
- **industries** (required): List of target industries.
34+
- **partners** (optional): List of partner organizations.
35+
- **GitHub repo URL** (required): Used to populate `links.github` and `links.bugs`.
36+
- **Additional subpages** (optional): Beyond the standard set (getting-started, cluster-sizing, ideas-for-customization, troubleshooting).
37+
38+
## Step 2: Determine format and naming
39+
40+
- **Always use AsciiDoc (`.adoc`)** unless the user explicitly requests Markdown (`.md`).
41+
- File names: lowercase, dash-separated (e.g. `getting-started.adoc`, `cluster-sizing.adoc`).
42+
- Pattern directories: `content/patterns/<pattern-name>/` with `_index.adoc` and subpages.
43+
- Learn pages: `content/learn/<page-name>.adoc`.
44+
45+
## Step 3: Generate files from templates
46+
47+
Read the applicable reference file before generating content:
48+
49+
- **Learn page**: Read [references/learn-page.md](references/learn-page.md) for frontmatter schema, menu hierarchy, and body structure.
50+
- **Pattern page set**: Read [references/pattern-set.md](references/pattern-set.md) for index frontmatter schema, standard subpages, and body templates.
51+
52+
### Generation rules
53+
54+
1. Create files using the template structure, substituting the gathered metadata.
55+
2. For patterns, create the full standard page set:
56+
- `_index.adoc` — pattern overview
57+
- `getting-started.adoc` (weight 10) — prerequisites and deployment procedure
58+
- `cluster-sizing.adoc` (weight 20) — resource requirements
59+
- `ideas-for-customization.adoc` (weight 30) — customization suggestions
60+
- `troubleshooting.adoc` (weight 40) — common issues and solutions
61+
- Plus any additional subpages requested by the user.
62+
3. For AsciiDoc files, always include these attributes at the top of the body:
63+
```
64+
:toc:
65+
:imagesdir: /images
66+
:_content-type: ASSEMBLY
67+
include::modules/comm-attributes.adoc[]
68+
```
69+
4. **Write real content** based on the topic — not just placeholder comments. Draft substantive sections that the user can refine. Use shared AsciiDoc attributes from `modules/comm-attributes.adoc` instead of hard-coding product names.
70+
5. Use `[id="section-id"]` anchors before major AsciiDoc sections.
71+
72+
## Step 4: Style review using doc-review guides
73+
74+
After generating the files, perform a comprehensive style review using the doc-review guide files. Read the relevant guides from `../doc-review/guides/` and check the generated content against them. The two-pass approach from doc-review applies here: scan the generated content first, then load only the guides whose rules are relevant.
75+
76+
**Important**: Because skills cannot invoke other skills directly, perform the review inline by reading the guide files yourself rather than trying to call the doc-review skill. The guides live at `../doc-review/guides/` relative to this skill's directory.
77+
78+
For each generated file:
79+
1. Scan for likely violations (contractions, passive voice, title case, banned words, etc.).
80+
2. Read the matching guide files from `../doc-review/guides/`.
81+
3. Apply must-fix issues automatically.
82+
4. Present recommended improvements to the user for their decision.
83+
84+
## Step 5: Present results
85+
86+
After generating and validating, present:
87+
1. A file list with full paths and a one-line description of each file.
88+
2. Any style fixes that were applied during generation and review.
89+
3. Suggested next steps (e.g. adding images, creating reusable modules, running `make serve` to preview).

‎.rulesync/skills/doc-create/references/learn-page.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Learn page reference
2+
3+
## Frontmatter
4+
5+
### Top-level learn page
6+
7+
```yaml
8+
---
9+
menu: learn
10+
title: Page title in sentence case
11+
weight: 10
12+
aliases: /learn/page-name/
13+
---
14+
```
15+
16+
### Child learn page (nested under a parent)
17+
18+
```yaml
19+
---
20+
menu:
21+
learn:
22+
parent: Parent Menu Label
23+
title: Page title in sentence case
24+
weight: 20
25+
aliases: /learn/page-name/
26+
---
27+
```
28+
29+
### Optional fields
30+
31+
| Field | When to use |
32+
|---|---|
33+
| `layout: default` | Only if the page needs a non-standard layout (e.g. landing pages like `quickstart.adoc`) |
34+
| `aliases` | Add an alias matching the old URL if migrating content, or `/learn/<page-name>/` for clean URLs |
35+
36+
### Known parent menu labels
37+
38+
These parent labels exist in the current site — use them exactly as shown when creating child pages:
39+
40+
- `Patterns quick start`
41+
- `Validated patterns frameworks`
42+
43+
## AsciiDoc body template
44+
45+
```asciidoc
46+
---
47+
menu: learn
48+
title: Page title
49+
weight: 10
50+
---
51+
52+
:toc:
53+
:imagesdir: /images
54+
:_content-type: ASSEMBLY
55+
include::modules/comm-attributes.adoc[]
56+
57+
[id="page-anchor-id"]
58+
= Page title
59+
60+
Introductory paragraph explaining the purpose and scope of this page. Focus on what the user can accomplish.
61+
62+
[id="first-section"]
63+
== First section heading
64+
65+
Content here. Use:
66+
67+
* Bulleted lists for related items.
68+
* `[source,terminal]` blocks for commands.
69+
* `.Prerequisites` and `.Procedure` labels for procedural sections.
70+
71+
[id="second-section"]
72+
== Second section heading
73+
74+
Additional content.
75+
```
76+
77+
### Procedural section example
78+
79+
```asciidoc
80+
[id="deploying-the-component"]
81+
== Deploying the component
82+
83+
.Prerequisites
84+
85+
* An OpenShift cluster with dynamic `StorageClass` provisioning.
86+
* The `oc` CLI installed and authenticated.
87+
88+
.Procedure
89+
90+
. Clone the repository:
91+
+
92+
[source,terminal]
93+
----
94+
$ git clone <repo-url>
95+
----
96+
97+
. Change to the project directory:
98+
+
99+
[source,terminal]
100+
----
101+
$ cd <project-dir>
102+
----
103+
104+
. Deploy the pattern:
105+
+
106+
[source,terminal]
107+
----
108+
$ ./pattern.sh make install
109+
----
110+
```
111+
112+
### Concept section example
113+
114+
```asciidoc
115+
[id="benefits-of-gitops"]
116+
== Benefits of GitOps
117+
118+
GitOps provides the following advantages:
119+
120+
* **Declarative configuration**: The desired state is stored in Git.
121+
* **Auditability**: Every change is tracked through Git history.
122+
* **Automation**: Changes are automatically applied by the GitOps operator.
123+
```
124+
125+
## Markdown body template
126+
127+
Use only when the user explicitly requests Markdown.
128+
129+
```markdown
130+
---
131+
menu: learn
132+
title: Page title
133+
weight: 10
134+
---
135+
136+
# Page title
137+
138+
Introductory paragraph explaining the purpose and scope of this page.
139+
140+
## First section heading
141+
142+
Content here.
143+
144+
## Second section heading
145+
146+
Additional content.
147+
```
148+
149+
## Naming conventions
150+
151+
- File names: lowercase, dash-separated (e.g. `getting-started-with-gitops.adoc`).
152+
- Placed directly in `content/learn/` (flat structure, no subdirectories).
153+
- Use descriptive names that reflect the content (e.g. `secrets-management.adoc`, not `secrets.adoc`).

0 commit comments

Comments
 (0)