General documentation standards for README, AsciiDoc, and technical documentation
General documentation standards for README, AsciiDoc, and technical documentation
npx skills add https://github.com/cuioss/cui-llm-rules --skill cui-documentation复制此命令并粘贴到 Claude Code 中以安装该技能
CUI Java unit testing standards and patterns with JUnit 5, generators, and value object testing
CDI and Quarkus development standards for CUI projects, including CDI aspects, container configuration, testing, and native optimization
Modern CSS standards covering essentials, responsive design, quality practices, and tooling for CUI projects
Cypress E2E testing standards including framework adaptations, test organization, and best practices
ESLint, Prettier, and StyleLint configuration standards for JavaScript code quality and formatting, including flat config setup, rule management, and build integration
JavaScript project structure, package.json configuration, dependency management, and Maven integration standards for consistent project setup and builds
| name | cui-documentation |
| description | General documentation standards for README, AsciiDoc, and technical documentation |
| allowed-tools | ["Read","Edit","Write","Bash","Grep","Glob"] |
Standards for writing clear, maintainable technical documentation in CUI projects.
Note: This skill covers general documentation. For code documentation, use:
cui-javadoc for Java code documentationcui-frontend-development/jsdoc-standards.md for JavaScript documentationCRITICAL: Load current documentation standards based on context.
Always load core documentation standards:
Read: standards/documentation-core.md
Conditional loading based on context:
If creating or editing README files:
Read: standards/readme-structure.md
If working with AsciiDoc files:
Read: standards/asciidoc-formatting.md
If reviewing tone, style, or language (or comprehensive reviews):
Read: standards/tone-and-style.md
If organizing, restructuring, or reviewing documentation structure:
Read: standards/organization-standards.md
Extract key requirements from all loaded standards
Store in working memory for use during task execution
When to Execute: After loading standards
What to Analyze:
General Documentation Quality:
Tone and Style (if tone-and-style.md loaded):
Organization and Structure (if organization-standards.md loaded):
AsciiDoc Format (if .adoc files):
xref: format)README Structure (if README files):
Content Quality:
When to Execute: During documentation creation or review
What to Apply:
Core Documentation Principles:
AsciiDoc Formatting (if .adoc files):
README Files (README.adoc, */README.adoc):
:toc: macro (NOT :toc: left)toc::[] manually where TOC should appear= Module Name
:toc: macro
:toclevels: 3
:sectnums:
:source-highlighter: highlight.js
Brief module description.
toc::[]
== Core Concepts
General Documentation Files (not READMEs):
:toc: left for automatic left sidebar TOC:toc: macro= Document Title
:toc: left
:toclevels: 3
:toc-title: Table of Contents
:sectnums:
:source-highlighter: highlight.js
All AsciiDoc Files:
xref:path/to/file.adoc[Link Text] for cross-referencesREADME Structure (if README files):
Code Examples:
When to Execute: After creating or updating documentation
Quality Checks:
Tone and Style Verification:
AsciiDoc Format Verification (if .adoc):
xref: syntaxREADME Structure Verification (if README):
Content Quality Verification:
Build Verification (if applicable):
# Verify documentation builds successfully
mvn clean install -DskipTests
When to Execute: After creating or updating AsciiDoc files
Available Validation Scripts:
This skill includes two validation scripts in the scripts/ directory:
asciidoc-validator.sh - Format validation script
Usage:
# Validate a single file
scripts/asciidoc-validator.sh path/to/file.adoc
# Validate all files in a directory
scripts/asciidoc-validator.sh directory/
verify-adoc-links.py - Link verification script
Usage:
# Verify links in a single file
python3 scripts/verify-adoc-links.py --file path/to/file.adoc --report target/links.md
# Verify links in directory (non-recursive)
python3 scripts/verify-adoc-links.py --directory directory/ --report target/links.md
# Verify links recursively
python3 scripts/verify-adoc-links.py --directory directory/ --recursive --report target/links.md
Validation Workflow:
Run format validation:
scripts/asciidoc-validator.sh target_file_or_directory 2>&1
Run link verification:
mkdir -p target/asciidoc-reviewer
python3 scripts/verify-adoc-links.py --file target.adoc --report target/asciidoc-reviewer/links.md 2>&1
Distinguish link validation results:
xref:path[text] formatReview validation output and fix issues
Re-run validation to confirm fixes
Script Paths:
scripts/asciidoc-validator.sh and scripts/verify-adoc-links.pyWhen to Execute: After verification passes
Commit Standards:
= Document Title
:toc: left
:toclevels: 3
:toc-title: Table of Contents
:sectnums:
:source-highlighter: highlight.js
== Purpose
Brief description of the document's purpose.
== Related Documentation
* xref:other-document.adoc[Other Document]
* xref:../category/document.adoc[Category Document]
= Module Name
Concise description of the module's purpose and key features.
== Maven Coordinates
[source, xml]
----
<dependency>
<groupId>group.id</groupId>
<artifactId>artifact-id</artifactId>
</dependency>
----
== Core Concepts
=== Feature One
* Capability details
* Integration points
* Key benefits
== Usage Examples
=== Basic Usage
[source,java]
----
// Complete code example
----
== Configuration
=== Property Configuration
[source,properties]
----
# Configuration examples
----
[source,java]
----
@Test
void shouldValidateToken() {
// Test implementation
}
----
xref: not link:All documentation must pass:
All documentation standards are located in the standards/ directory: