Enhance abstract skill for DITA short descriptions

.claude/skills/abstract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: abstract
-description: Review or write abstract
+description: Review or write an abstract (also called a short description) for a documentation module
 ---
 # Review or write abstract
 
@@ -26,31 +26,13 @@ Abstracts typically contain the following information:
 
 When reviewing or writing the abstract, follow these principles:
 
-- Ensure the abstract explains the What and the Why as defined in the section "Definition of an abstract".
-  - For the `What` part, state the action or feature clearly. For example, what the user must do or can do (in procedure modules), what the user needs to understand (in concept modules), or what is being listed (in reference modules).
-  - For the `Why` part, state the business value, benefit, or goal. For example, why the user should complete the action (in procedure modules), why the concept is important to users (in concept modules), or why the user would look up the information (in reference modules).
-  - For the `Example use case part`, consider including in what situations a user might find the contents of the module useful.
-  - Do not simply repeat the heading of the module; build upon it.
-- Follow these user-centric language guidelines:
-  - Avoid documentation self-referential language (for example: avoid "This procedure..." or "This module").
-  - Avoid feature-centric language (for example: avoid "This feature...").
-  - Use user-centric language (for example: use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", "[Action] [what] to [why]").
+- 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.
-
-## Examples of good abstracts
-
-| Heading | Example abstract (procedure) |
-| :--- | :--- |
-| Browsing hosts in {ProjectWebUI} | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. |
-| Cloning hosts in {Project} | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
-| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |
-
-| Heading | Example abstract (concept) |
-| :--- | :--- |
-| Security considerations in {Project} | {Project} supports multiple security mechanisms to provide additional layers of protection. Implementing these security features enhances the overall security of your {Project} deployment. |
-| Overview of authentication methods in {Project} | The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements. |
-
-| Heading | Example abstract (reference) |
-| :--- | :--- |
-| Subscriptions usage data | For the purposes of expense management and to optimize your spending, track your subscriptions usage data that you can get from your {Project} environment and Red Hat. You can track usage, capacity, and utilization of your Red Hat subscriptions. |
-| Host global status overview | You can use the host global status in {Project} to see at a glance whether a host is OK, needs attention (Warning), or has errors. The status appears on the Hosts Overview page and helps you prioritize which hosts to investigate. |
+- 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)

.cursor/skills/abstract/references/concept.md

@@ -0,0 +1,13 @@
+# Abstract instructions: concept modules
+
+When the module is a concept module (is named `con_*.adoc` or includes `:_mod-docs-content-type: CONCEPT` as its first line), follow these rules for the abstract (short description):
+
+- Introduce the concept and provide a concise answer to the question "What is this?" and in some cases "How is this knowledge useful to the user?"
+- Avoid using the short description to lead in or build up to a topic.
+
+## Examples of good abstracts
+
+| Heading | Example abstract (concept) |
+| :--- | :--- |
+| Security considerations in {Project} | {Project} supports multiple security mechanisms to provide additional layers of protection. Implementing these security features enhances the overall security of your {Project} deployment. |
+| Overview of authentication methods in {Project} | The authentication methods you can configure depend on the authentication source you are using. If the native authentication features provided by {Project} are not sufficient for your use case, use this information to decide which external authentication provider best suits your requirements. |

.cursor/skills/abstract/references/procedure.md

@@ -0,0 +1,16 @@
+# Abstract instructions: procedure modules
+
+When the module is a procedure module (is named `proc_*.adoc` or includes `:_mod-docs-content-type: PROCEDURE` as its first line), follow these rules for the abstract (short description):
+- Explain the task that users can accomplish, the benefits of the task, and the purpose of the task.
+- Do not simply repeat the title.
+- Include information that will help users understand when the task is appropriate or necessary.
+- Use phrases such as "You can [action] to [benefit]", "To [goal], configure [feature]", or "[Action] [what] to [why]".
+- When the abstract is too short or generic, add more information about why the task is beneficial.
+
+## Examples of good abstracts
+
+| Heading | Example abstract (procedure) |
+| :--- | :--- |
+| Browsing hosts in {ProjectWebUI} | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. |
+| Cloning hosts in {Project} | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
+| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |

.cursor/skills/abstract/references/reference.md

@@ -0,0 +1,12 @@
+# Abstract instructions: reference modules
+
+When the module is a reference module (is named `ref_*.adoc` or includes `:_mod-docs-content-type: REFERENCE` as its first line), follow these rules for the abstract (short description):
+
+- Briefly describe what the reference item does, what it is, or what it is used for.
+
+## Examples of good abstracts
+
+| Heading | Example abstract (reference) |
+| :--- | :--- |
+| Subscriptions usage data | For the purposes of expense management and to optimize your spending, track your subscriptions usage data that you can get from your {Project} environment and Red Hat. You can track usage, capacity, and utilization of your Red Hat subscriptions. |
+| Host global status overview | You can use the host global status in {Project} to see at a glance whether a host is OK, needs attention (Warning), or has errors. The status appears on the Hosts Overview page and helps you prioritize which hosts to investigate. |