Add automated style guide

.claude/skills/abstract/SKILL.md

@@ -1,38 +1,35 @@
 ---
-name: abstract
+name: Abstracts
 description: Review or write an abstract (also called a short description) for a documentation module
 ---
-# Review or write abstract
+#### Overview
 
-## Overview
+An abstract is the first paragraph of a documentation module that helps readers and AI-powered search tools find the information they need and confirm they are in the right place.
 
-Review and improve the abstract for this file. Write it if it doesn't exist yet.
+An abstract follows after the module heading and is prefixed by the `[role="_abstract"]` AsciiDoc tag.
 
-## Definition of an abstract
+Abstracts typically contain:
+- The "What" - what the content covers
+- The "Why" - why it matters or when to use it
+- Where appropriate, an example use case
 
-An abstract is the first paragraph of the module.
-It follows after the module heading.
-It is prefixed by the `[role="_abstract"]` AsciiDoc tag.
+**Guidelines:**
+- Do not simply repeat the heading of the module; build upon it
+- Avoid self-referential language (e.g., "This procedure...", "This module...", "This table...")
+- Avoid feature-centric language (e.g., "This feature...")
+- Do not use sentence fragments
+- When addressing the user, address them as "you"
+- Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph
 
-Abstracts, also called short descriptions, help readers and AI-powered search tools find the information that they need and confirm that they are in the right place.
+**Module-type-specific guidelines:**
+- `CONCEPT` modules: See [references/concept.md](references/concept.md)
+- `PROCEDURE` modules: See [references/procedure.md](references/procedure.md)
+- `REFERENCE` modules: See [references/reference.md](references/reference.md)
 
-Abstracts typically contain the following information:
+#### Instructions
 
-- The "What"
-- The "Why"
-- Where appropriate, an example use case
-
-## Instructions
+Review and improve the abstract for this file. Write it if it doesn't exist yet.
 
-When reviewing or writing the abstract, follow these principles:
+When reviewing or writing the abstract, follow the guidelines in the Overview section.
 
-- Do not simply repeat the heading of the module; build upon it.
-- Avoid self-referential language (for example: avoid "This procedure...", "This module...", "This table...").
-- Avoid feature-centric language (for example: avoid "This feature...").
-- Do not use sentence fragments.
-- When addressing the user, address them as "you".
-- Follow these length constraints: 50-300 characters, 1-2 sentences, a single paragraph.
-- For module-type-specific abstract rules, look up the reference file that matches the `:_mod-docs-content-type:` AsciiDoc attribute in the module (open and apply that file in full):
-  - `CONCEPT` → [references/concept.md](references/concept.md)
-  - `PROCEDURE` → [references/procedure.md](references/procedure.md)
-  - `REFERENCE` → [references/reference.md](references/reference.md)
+For module-type-specific abstract rules, look up the reference file that matches the `:_mod-docs-content-type:` AsciiDoc attribute in the module (open and apply that file in full).

.claude/skills/heading/SKILL.md

@@ -1,57 +1,51 @@
 ---
-name: heading
+name: Headings
 description: Review or write heading
 ---
+#### Overview
 
-# Review or write heading
+Headings should be clear, concise, and use familiar keywords that help users understand what the content covers.
 
-## Overview
+**General principles for all headings:**
+- Make the heading 3-11 words long
+- Use clear headings with familiar keywords for users
+- Ensure the heading summarizes the contents of the part of the documentation it introduces
 
-Review and improve the heading for this file.
-Write it if it doesn't exist yet.
+**Module-type-specific principles:**
+- **Concepts** (con_*.adoc): Do not start with a gerund or verb. Use a noun phrase and include nouns that appear in the body text.
+- **Procedures** (proc_*.adoc): Start the heading with a gerund (e.g., "Configuring...", "Creating...").
+- **References** (ref_*.adoc): Do not start with a gerund or verb. Include nouns that appear in the body text.
+- **Assemblies** containing procedures: Start the heading with a gerund.
+- **Assemblies** containing only concepts or references: Do not start with a gerund or verb. Use a noun phrase.
 
-## Instructions
+#### Examples
 
-Follow these general principles for all headings:
+**Concept headings:**
+- Provisioning methods in {Project}
+- Security considerations in {Project}
+- Host groups overview
 
-* Make the heading 3-11 words long.
-* Use clear headings with familiar keywords for users.
-* Ensure the heading summarizes the contents of the part of the documentation it introduces.
+**Procedure headings:**
+- Deploying SSH keys during provisioning
+- Opening required ports
+- Configuring pull-based transport for remote execution
 
-Additional principles for specific heading types:
+**Reference headings:**
+- Job template examples and extensions
+- Host parameter hierarchy
+- Operating system requirements
 
-* For concepts (con_*.adoc): Do not start the heading with a gerund or verb. Use a noun phrase and include nouns or noun phrases that appear in the body text.
-* For procedures (proc_*.adoc): Start the heading with a gerund.
-* For references (ref_*.adoc): Do not start the heading with a gerund or verb. Include nouns that appear in the body text.
-* For assemblies (the first con_*.adoc in an assembly_*.adoc) that contain at least one procedure: Start the heading with a gerund.
-* For assemblies (the first con_*.adoc in an assembly_*.adoc) that contain only concepts or references: Do not start the heading with a gerund or verb. Use a noun phrase.
+**Assembly headings:**
+- Connecting AI applications to the MCP server for {Project}
+- Configuring {SmartProxy} and hosts to authenticate with SSH certificates during remote execution
+- Content and patch management with {Project}
 
-## Post-command cleanup
+#### Instructions
 
-* If you rename a heading, use the `.cursor/skills/refactor-adoc.md` command to update the module's ID, filename, and all references and links to the module in the repository.
+Review and improve the heading for this file. Write it if it doesn't exist yet.
 
-## Examples of good headings
+Follow the principles outlined in the Overview section above.
 
-Concept headings:
+#### Post-command cleanup
 
-* Provisioning methods in {Project}
-* Security considerations in {Project}
-* Host groups overview
-
-Procedure headings:
-
-* Deploying SSH keys during provisioning
-* Opening required ports
-* Configuring pull-based transport for remote execution
-
-Reference headings:
-
-* Job template examples and extensions
-* Host parameter hierarchy
-* Operating system requirements
-
-Assembly headings:
-
-* Connecting AI applications to the MCP server for {Project}
-* Configuring {SmartProxy} and hosts to authenticate with SSH certificates during remote execution
-* Content and patch management with {Project}
+If you rename a heading, use the `/refactor-adoc` command to update the module's ID, filename, and all references and links to the module in the repository.

.claude/skills/personas/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: User personas
+description: Understand and apply Foreman user personas when writing documentation
+---
+#### Overview
+
+Foreman documentation targets different user personas with varying responsibilities and permissions. Understanding the target persona helps ensure documentation addresses the user's needs and capabilities appropriately.
+
+**User persona:**
+- Has limited permissions
+- Runs regular Foreman operations
+- Example responsibilities: managing content, provisioning hosts, managing hosts
+
+**Admin persona:**
+- Has unlimited permissions, including root access to the Foreman Server
+- Example responsibilities: managing Foreman server, configuring system settings
+
+**Architect persona:**
+- Has no permissions, does not perform practical administrative or management tasks
+- Example responsibilities: evaluating whether Foreman/Katello meets organizational needs, planning deployment architecture
+
+**When to consider personas:**
+- Use persona-appropriate language and assume persona-appropriate knowledge
+- For User persona: Focus on tasks they can perform with limited permissions
+- For Admin persona: Include system administration and configuration tasks
+- For Architect persona: Provide planning, architecture, and decision-making information
+
+#### Instructions
+
+When reviewing or writing documentation, identify the target persona and ensure:
+
+1. The content matches the persona's permission level and responsibilities
+2. Technical depth is appropriate for the persona's expertise
+3. Prerequisites assume the persona's typical environment
+4. Examples and use cases reflect the persona's real-world scenarios
+
+If content targets multiple personas, consider splitting it or clearly indicating which sections apply to which personas.

.claude/skills/prerequisites/SKILL.md

@@ -1,43 +1,51 @@
 ---
-name: prerequisites
+name: Prerequisites
 description: Review or add prerequisites
 ---
-# Review or add prerequisites
-
-## Overview
-
-Review prerequisites in this file to make sure they are labeled correctly and use consistent formatting. Prerequisites are a bulleted list of conditions that must be satisfied before the user starts the procedure.
-
-## Instructions
+#### Overview
+
+Prerequisites are a bulleted list of conditions that must be satisfied before the user starts a procedure. Only procedure modules (proc_*.adoc) can include a `.Prerequisites` section.
+
+**What prerequisites are:**
+- Checks that are true before the user begins
+- Conditions the user must have completed beforehand
+- Items the user must have ready
+- Actions that the user, another person, or technology has completed before the user can begin
+
+**Formatting guidelines:**
+- The first word of each prerequisite must be capitalized
+- Each prerequisite must start with a bullet point
+- Prerequisites must not use imperative voice
+- If prerequisites are full sentences, end all with a period
+- If prerequisites are sentence fragments, do not use any end punctuation
+- Use passive voice for prerequisites representing an action not completed by the current user
+- Prerequisites must use parallel language (all sentences or all fragments, not mixed)
+
+**Content guidelines:**
+- Focus on relevant prerequisites that users might not otherwise be aware of
+- Do not list obvious prerequisites
+- Do not include procedure steps in prerequisites
+- Do not exceed 10 prerequisites
+
+#### Examples
+
+**Good prerequisites:**
+- The `kernelcare` package is installed on your hosts.
+- The base system of the {SmartProxy} is registered to the newly upgraded {ProjectServer}.
+- Your user account has a role that grants the `view_policies` permission.
+- You are logged in to the registry.redhat.io container registry.
+- If you use `dzdo` for Ansible jobs, the `community.general` Ansible collection must be installed.
+
+**Bad prerequisites (and why):**
+- You are logged in. *(Obvious prerequisite)*
+- The host is registered to {Project}. *(Obvious prerequisite)*
+- At least one host exists in {Project}. *(Obvious prerequisite)*
+- Ensure the `kernelcare` package is installed on your hosts. *(Uses imperative voice)*
+- Install the `kernelcare` package on your hosts. *(Phrased like a procedure step)*
+
+#### Instructions
 
 1. Only process procedure modules (proc_*.adoc). These are the only modules that can include a `.Prerequisites` section.
-2. If a section titled `.Prerequisites` exists in the file, ensure it uses consistent formatting:
-    - The first word of each prerequisite must be capitalized.
-    - Each prerequisite must start with a bullet point.
-    - Prerequisites must not use imperative voice.
-    - If the prerequisites are full sentences, end all prerequisites with a period.
-    - If the prerequisites are sentence fragments, do not use any end punctuation.
-    - Use passive voice for prerequisites that represent an action that is not completed by the current user. For example, having a configuration enabled by a system admin.
-    - Prerequisites must use parallel language. For example, if one bullet is a complete sentence, write the other bullets as complete sentences.
-2. If a section titled `.Prerequisites` exists in the file, ensure it contains information suitable for prerequisites:
-    - Prerequisites are checks that are true, checks that the user must have completed before they begin a procedure, or items that the user must have ready before beginning a procedure. Prerequisites can also be actions that the user, another person, or piece of technology has completed before the user can begin the procedure.
-    - Focus on relevant prerequisites that users might not otherwise be aware of. Do not list obvious prerequisites.
-    - Do not include procedure steps in prerequisites. If `.Prerequisites` includes a prerequisite that would be more suitable as a procedure step, move it to the `.Procedure` section.
-    - Do not exceed 10 prerequisites. If `.Prerequisites` includes more than 10 list items, flag this as an issue for human review.
-3. If a procedure module does not include `.Prerequisites` section, scan the module to identify steps that meet criteria for prerequisites. If a step or steps like this exist, create a `.Prerequisites` section and rephrase the step or steps as prerequisites in this section.
-
-## Examples of good prerequisites
-
-* The `kernelcare` package is installed on your hosts.
-* The base system of the {SmartProxy} is registered to the newly upgraded {ProjectServer}.
-* Your user account has a role that grants the `view_policies` permission.
-* You are logged in to the registry.redhat.io container registry.
-* If you use `dzdo` for Ansible jobs, the `community.general` Ansible collection must be installed.
-
-## Examples of bad prerequisites
-
-* You are logged in. (This is an obvious prerequisite.)
-* The host is registered to {Project}. (This is an obvious prerequisite.)
-* At least one host exists in {Project}. (This is an obvious prerequisite.)
-* Ensure the `kernelcare` package is installed on your hosts. (This prerequisite uses imperative voice.)
-* Install the `kernelcare` package on your hosts. (This prerequisite is phrase like a procedure step.)
+2. If a section titled `.Prerequisites` exists in the file, ensure it uses consistent formatting as described in the Overview.
+3. If a section titled `.Prerequisites` exists in the file, ensure it contains information suitable for prerequisites.
+4. If a procedure module does not include a `.Prerequisites` section, scan the module to identify steps that meet criteria for prerequisites. If such steps exist, create a `.Prerequisites` section and rephrase the steps as prerequisites.

.claude/skills/refactor-adoc/SKILL.md

@@ -1,22 +1,30 @@
 ---
-name: refactor-adoc
+name: Rename a module
 description: Refactor adoc file by a given title
 disable-model-invocation: true
 ---
-# Refactor adoc file by a given title
+#### Overview
 
-## Overview
-
-Change the title (if present), ID (if present), and file name of an assembly, module, or snippet according to a new title.
-Update the includes and any ID references across all documentation.
-
-Usage:
+This command changes the title, ID, and filename of an assembly, module, or snippet according to a new title, and updates all includes and ID references across the documentation.
 
+**Usage:**
 ```
 /refactor-adoc @old-file.adoc "New title"
 ```
 
-## Instructions
+**What it does:**
+- Renames the file with the appropriate prefix (e.g., `proc_new-title.adoc`)
+- Updates the ID if present (e.g., `[id="new-title_{context}"]`)
+- Updates the title if present (e.g., `= New title`)
+- Updates all `include::` directives that reference this file
+- Updates all cross-references to the old ID throughout the documentation
+
+**When to use:**
+- When you need to rename a documentation file to better match its content
+- After significantly revising the content of a module
+- When improving heading clarity requires filename changes
+
+#### Instructions
 
 Refactor the following `.adoc` file according to the following title.
 Follow these principles: