documentation
Write concise Diataxis docs for gh-aw with Starlight markdown conventions.
How do I install this agent skill?
npx skills add https://github.com/github/gh-aw --skill documentationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides guidelines and best practices for writing documentation using the Diátaxis framework and Astro Starlight. It contains no executable code or security risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Documentation
Documentation lives in docs/, uses GitHub-flavored Markdown, renders with Astro Starlight, and follows Diátaxis.
Diátaxis Framework
Organize documentation into four Diátaxis types:
1. Tutorials (Learning-Oriented)
Purpose: Guide beginners through achieving a specific outcome to build confidence.
- Start with what the user will build or achieve
- Provide a clear, step-by-step path from start to finish
- Include concrete examples and working code
- Assume minimal prior knowledge
- Focus on the happy path (avoid edge cases and alternatives)
- End with a working result the user can see and use
- Use imperative mood: "Create a file", "Run the command"
Avoid: Explaining concepts in depth, multiple options, troubleshooting
2. How-to Guides (Goal-Oriented)
Purpose: Show how to solve a specific real-world problem or accomplish a particular task.
- Title format: "How to [accomplish specific goal]"
- Assume the user knows the basics
- Focus on practical steps to solve one problem
- Include necessary context but stay focused
- Show multiple approaches only when genuinely useful
- End when the goal is achieved
- Use imperative mood: "Configure the setting", "Add the following"
Avoid: Teaching fundamentals, explaining every detail, being exhaustive
3. Reference (Information-Oriented)
Purpose: Provide accurate, complete technical descriptions of the system.
- Organized by structure (CLI commands, configuration options, API endpoints)
- Comprehensive and authoritative
- Consistent format across all entries
- Technical accuracy is paramount
- Include all parameters, options, and return values
- Use descriptive mood: "The command accepts", "Returns a string"
- Minimal narrative or explanation
Avoid: Instructions, tutorials, opinions on usage
4. Explanation (Understanding-Oriented)
Purpose: Clarify and illuminate topics to deepen understanding.
- Discuss why things are the way they are
- Explain design decisions and tradeoffs
- Provide context and background
- Connect concepts to help form mental models
- Discuss alternatives and their implications
- Use indicative mood: "This approach provides", "The engine uses"
Avoid: Step-by-step instructions, exhaustive reference material
General Style Guidelines
- Tone: Neutral, technical, not promotional
- Voice: Avoid "we", "our", "us" (use "the tool", "this command")
- Headings: Use markdown heading syntax, not bold text as headings
- Lists: Avoid long bullet point lists; prefer prose with structure
- Code samples: Minimal and focused; exclude optional fields unless relevant
- Language tag: Use
awfor agentic workflow snippets with YAML frontmatter
Example workflow code block:
on: push
# Your workflow steps here
GitHub-Flavored Markdown Syntax
Documentation files use GitHub-flavored markdown with Astro Starlight for rendering. Key syntax elements:
Frontmatter
Every documentation page must have frontmatter:
title: Page Title
description: Brief description for SEO and navigation
GitHub Alerts
Use GitHub's alert syntax for notes, tips, warnings, and cautions:
> [!NOTE]
> Important information the reader should notice.
> [!TIP]
> Helpful advice for the reader.
> [!WARNING]
> Warning about potential issues or pitfalls.
> [!CAUTION]
> Critical warning about dangerous operations.
> [!IMPORTANT]
> Key information users need to know.
Code Blocks
- Use syntax highlighting with language tags
- Add
titleattribute for file names:```yaml title=".github/workflows/example.yml" - Use
awlanguage for agentic workflow files with YAML frontmatter - Add
wrapfor line wrapping:```aw wrap
Links
- Internal links: Use relative paths between documentation pages
- External links: Open in new tab automatically
- Link text: Use descriptive text, avoid "click here"
Tabs
Use tabs for showing alternatives (e.g., different languages, platforms):
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs>
<TabItem label="npm">
```bash
npm install package
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add package
```
</TabItem>
</Tabs>
Cards
Use cards for navigation or highlighting multiple options:
import { Card, CardGrid } from '@astrojs/starlight/components';
<CardGrid>
<Card title="Getting Started" icon="rocket">
Quick introduction to the basics.
</Card>
<Card title="Advanced Usage" icon="setting">
Deep dive into advanced features.
</Card>
</CardGrid>
Remember: Keep components minimal. Prefer standard markdown when possible.
Content to Avoid
- "Key Features" sections
- Marketing language or selling points
- Excessive bullet points (prefer structured prose)
- Overly verbose examples with all optional parameters
- Mixing documentation types (e.g., tutorials that become reference)
Avoiding Documentation Bloat
Documentation bloat reduces clarity and makes content harder to navigate. Common types of bloat include:
Types of Documentation Bloat
- Duplicate content: Same information repeated in different sections
- Excessive bullet points: Long lists that could be condensed into prose or tables
- Redundant examples: Multiple examples showing the same concept
- Verbose descriptions: Overly wordy explanations that could be more concise
- Repetitive structure: The same "What it does" / "Why it's valuable" pattern overused
Writing Concise Documentation
When editing documentation, focus on:
Consolidate bullet points:
- Convert long bullet lists into concise prose or tables
- Remove redundant points that say the same thing differently
Eliminate duplicates:
- Remove repeated information
- Consolidate similar sections
Condense verbose text:
- Make descriptions more direct and concise
- Remove filler words and phrases
- Keep technical accuracy while reducing word count
Standardize structure:
- Reduce repetitive "What it does" / "Why it's valuable" patterns
- Use varied, natural language
Simplify code samples:
- Remove unnecessary complexity from code examples
- Focus on demonstrating the core concept clearly
- Eliminate boilerplate or setup code unless essential for understanding
- Keep examples minimal yet complete
- Use realistic but simple scenarios
Example: Before and After
Before (Bloated):
### Tool Name
Description of the tool.
- **What it does**: This tool does X, Y, and Z
- **Why it's valuable**: It's valuable because A, B, and C
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
- **When to use**: Use it when you need X
- **Benefits**: Gets you benefit A, benefit B, benefit C
- **Learn more**: [Link](url)
After (Concise):
### Tool Name
Description of the tool that does X, Y, and Z to achieve A, B, and C.
Use it when you need X by following steps 1-5. [Learn more](url)
Documentation Quality Guidelines
- Preserve meaning: Never lose important information
- Be surgical: Make precise edits, don't rewrite everything
- Maintain tone: Keep the neutral, technical tone
- Test locally: Verify links and formatting are still correct
Structure by File Type
- Getting Started: Tutorial format
- How-to Guides: Goal-oriented, one task per guide
- CLI Reference: Reference format, complete command documentation
- Concepts: Explanation format, building understanding
- API Reference: Reference format, complete API documentation
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/github/gh-aw/documentation">View documentation on skillZs</a>