From dita-tools
Rewrites short descriptions in AsciiDoc files for clarity, conciseness, and DITA compliance. Use when fixing abstracts, improving summaries, or enhancing short descriptions in topics.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin dita-toolsThis skill is limited to using the following tools:
Analyze and rewrite short descriptions in AsciiDoc files for better clarity, conciseness, and DITA compliance.
Adds missing [role="_abstract"] attributes to AsciiDoc files via Ruby script for DITA short description support. Use when marking short descriptions or preparing files for DITA conversion.
Assesses CQA parameters P8-P11 for titles and short descriptions in Red Hat modular documentation, checking clarity, character limits, DITA conventions, and quality criteria.
Reviews AsciiDoc (.adoc) files for Red Hat modular documentation compliance: module types (concept, procedure, reference), assembly structure, anchor IDs with _{context}, context variables, and include directives.
Share bugs, ideas, or general feedback.
Analyze and rewrite short descriptions in AsciiDoc files for better clarity, conciseness, and DITA compliance.
This skill provides LLM-guided analysis and rewriting of short descriptions (paragraphs marked with [role="_abstract"]). Use this skill when existing short descriptions need improvement, not just when the abstract attribute is missing.
For adding the [role="_abstract"] attribute to files that don't have it, use the dita-add-shortdesc-abstract skill instead.
A short description is the first paragraph after the document title, marked with [role="_abstract"]. It provides a concise summary of the topic's purpose and is used as:
Constraint: A short description must be exactly one paragraph, under 50 words.
Concept topics answer "what is this?" and "why should I care?" Start with a brief definition if the term is unfamiliar. Make the main point clear.
Poor (repeats title, lead-in style):
= About model optimization
[role="_abstract"]
This topic explains about model optimization.
Good (standalone, explains value):
= About model optimization
[role="_abstract"]
Model optimization reduces neural network size and inference time through techniques like quantization and pruning, enabling AI applications to run efficiently on resource-constrained devices without significant accuracy loss.
Procedure topics explain what the task does, its benefits or purpose, and when or why the user should perform it. Include who performs the task if relevant.
Poor (states the obvious):
= Configuring authentication
[role="_abstract"]
Follow these steps to configure authentication.
Good (explains purpose and benefit):
= Configuring authentication
[role="_abstract"]
Configure LDAP authentication to enable single sign-on for your organization, allowing users to access the application with their existing corporate credentials.
Good (includes who and when):
= Rotating encryption keys
[role="_abstract"]
Cluster administrators should rotate encryption keys annually or immediately after a security incident to maintain compliance and protect sensitive data at rest.
Reference topics describe what the items are, what they do, and what they're used for. Use consistent phrasing across topics.
Poor (vague, no context):
= Configuration parameters
[role="_abstract"]
The following table lists configuration parameters.
Good (describes purpose and usage):
= Configuration parameters
[role="_abstract"]
The following configuration parameters control memory allocation, connection pooling, and timeout behavior for the database driver. Set these values in the `application.properties` file before starting the server.
Good (consistent reference style):
= Environment variables for the CLI
[role="_abstract"]
Use the following environment variables to configure authentication, output format, and logging behavior when running commands non-interactively or in CI/CD pipelines.
When the user asks to rewrite or improve short descriptions:
[role="_abstract"])1. Read the file
2. Identify content type from :_mod-docs-content-type: attribute
3. Find the [role="_abstract"] paragraph
4. Analyze the full module content
5. Draft a new short description that:
- Summarizes the topic's purpose
- Stays under 50 words
- Follows content-type-specific guidance
6. Edit the file to replace the old short description
| Problem | Solution |
|---|---|
| Repeats the title | Summarize purpose/value instead |
| Starts with "This topic..." | Start with actionable content |
| Too vague | Add specific details about what/why |
| Too long (>50 words) | Condense to essential points |
| Lead-in style | Make it standalone and complete |
| States the obvious | Explain benefits or context |
[role="_abstract"] to files missing itThis skill helps improve content flagged by: .vale/styles/AsciiDocDITA/ShortDescription.yml