hex1b: Skill for Claude Code

Documentation Writer Skill

This skill provides guidelines for AI coding agents to help maintainers produce accurate and easy-to-maintain documentation for the Hex1b project. The repository contains two primary types of documentation, each serving different audiences and following different conventions.

Documentation Types

1. XML API Documentation

Location: C# source files in src/Hex1b/
Audience: Library consumers, API reference generators, IDE intellisense users
Format: XML doc comments (///)
Build Setting: GenerateDocumentationFile is enabled in src/Hex1b/Hex1b.csproj

Purpose

XML documentation comments provide:

• Inline help in IDEs (IntelliSense, code completion)
• Generated API reference documentation
• Contract documentation for public APIs
• Usage examples for complex APIs

Best Practices for XML Documentation

1. Document All Public APIs

Required for:

• Public classes, structs, records, enums
• Public properties and fields
• Public methods and constructors
• Public events and delegates

Example:

/// <summary>
/// Represents a color that can be used in the terminal.
/// </summary>
public readonly struct Hex1bColor
{
    /// <summary>
    /// Creates a color from RGB values.
    /// </summary>
    /// <param name="r">Red component (0-255)</param>
    /// <param name="g">Green component (0-255)</param>
    /// <param name="b">Blue component (0-255)</param>
    /// <returns>A new Hex1bColor instance with the specified RGB values.</returns>
    public static Hex1bColor FromRgb(byte r, byte g, byte b) => new(r, g, b);
}

2. Write Clear, Concise Summaries

• Start with a verb (e.g., "Creates", "Gets", "Sets", "Calculates")
• Keep it to one or two sentences
• Describe what it does, not how it does it
• Use third person ("Creates a widget" not "Create a widget")

Good:

/// <summary>
/// Creates a Layout that wraps a single child widget with clipping enabled.
/// </summary>