Skip to content

Commit 6a53b12

Browse files
gaurav-nelsongaurav-nelson
committed
feat: Add doc-review and doc-create skill for AI agents
1 parent 5b0e90c commit 6a53b12

31 files changed

Lines changed: 1787 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: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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 when creating new docs, pages, patterns, or learn content.
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: Quick style check
73+
74+
Before presenting the result, read these high-impact style guides from `../doc-review/guides/` and verify the generated content complies:
75+
76+
| Priority | Guide | Key check |
77+
|---|---|---|
78+
| 1 | `titles-and-headings.md` | Gerund headings for procedures, noun phrases for concepts |
79+
| 2 | `capitalization.md` | Sentence-style capitalization in all headings |
80+
| 3 | `minimalism.md` | No self-referential text, no fluff, concise sentences |
81+
| 4 | `passive-voice.md` | Active voice in instructions |
82+
| 5 | `future-tense.md` | Present tense throughout |
83+
| 6 | `contractions.md` | No contractions |
84+
| 7 | `avoid-these-words.md` | No banned words |
85+
| 8 | `conscious-language.md` | Inclusive terminology |
86+
87+
Fix any violations in the generated files before presenting them.
88+
89+
## Step 5: Full style review with doc-review
90+
91+
After generating the files, run the **doc-review** skill against all created files for a comprehensive review using the full set of 24 style guides. This catches issues beyond the quick check in Step 4 (e.g. phrasal verbs, comma usage, possessives, link text, UI element formatting, command-line conventions, and format-specific rules).
92+
93+
Invoke the doc-review skill with the path to the created files:
94+
- For a learn page: pass the single file path (e.g. `content/learn/page-name.adoc`).
95+
- For a pattern page set: pass the pattern directory (e.g. `content/patterns/pattern-name/`).
96+
97+
Apply must-fix issues automatically. Present recommended improvements to the user for their decision.
98+
99+
### Output summary
100+
101+
After generating and validating, present:
102+
1. A file list with full paths and a one-line description of each file.
103+
2. Any style fixes that were applied during generation and review.
104+
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)