Agent Skills: Documentation Workflow

Skill Variant: Use this skill for autonomous documentation generation with structured templates. For interactive documentation tasks with user feedback, use documentation instead.

Documentation Workflow

Summary

Goal: Autonomously generate or update code documentation (XML docs, JSDoc, API docs, architecture docs) following platform conventions.

• Code Comments: XML docs for C# public APIs, JSDoc for TypeScript, inline for complex logic
• API Documentation: Endpoint descriptions, request/response schemas, error codes
• Architecture Documentation: Component diagrams, data flow, integration guides
• Comment Types: /// <summary> for APIs, // TODO: for planned work, // HACK: for workarounds

Key Principles:

• Explain "why" not "what" -- never state the obvious
• Keep documentation close to code, update when code changes
• Use this skill for autonomous generation; use documentation for interactive tasks

When to Use This Skill

• Creating API documentation
• Writing code comments
• Updating README files
• Generating architecture documentation

Documentation Types

1. Code Comments

• XML docs for public APIs
• Inline comments for complex logic
• TODO/FIXME for technical debt

2. API Documentation

• Endpoint descriptions
• Request/response schemas
• Error codes and handling

3. Architecture Documentation

• Component diagrams
• Data flow documentation
• Integration guides

Pattern 1: C# XML Documentation

/// <summary>
/// Saves or updates an employee entity.
/// </summary>
/// <remarks>
/// This command handles both create and update operations.
/// For new employees, the Id should be null or empty.
/// </remarks>
public sealed class SaveEmployeeCommand : PlatformCqrsCommand<SaveEmployeeCommandResult>
{
    /// <summary>
    /// The unique identifier of the employee.
    /// Null or empty for new employees.
    /// </summary>
    public string? Id { get; set; }

    /// <summary>
    /// The employee's full name.
    /// </summary>
    /// <value>Must be non-empty and max 200 characters.</value>
    public string Name { get; set; } = string.Empty;
}

Pattern 2: TypeScript JSDoc

/**
 * Manages the feature list state and operations.
 *
 * @example
 * ```typescript
 * @Component({ providers: [FeatureListStore] })
 * export class FeatureListComponent {
 *   constructor(private store: FeatureListStore) {
 *     store.loadItems();
 *   }
 * }
 * ```
 */
@Injectable()
export class FeatureListStore extends PlatformVmStore<FeatureListState> {
  /**
   * Loads items from the API with current filters.
   * Use `isLoading$('loadItems')` to check loading status.
   */
  public loadItems = this.effectSimple(() => /* ... */);
}

Pattern 3: API Endpoint Documentation

/// <summary>
/// Employee management endpoints.
/// </summary>
[ApiController]
[Route("api/[controller]")]
[PlatformAuthorize]
public class EmployeeController : PlatformBaseController
{
    /// <summary>
    /// Retrieves a paginated list of employees.
    /// </summary>
    /// <response code="200">Returns the employee list.</response>
    /// <response code="401">Unauthorized.</response>
    [HttpGet]
    [ProducesResponseType(typeof(GetEmployeeListQueryResult), StatusCodes.Status200OK)]
    public async Task<IActionResult> GetList([FromQuery] GetEmployeeListQuery query)
        => Ok(await Cqrs.SendAsync(query));
}

Documentation Guidelines

DO

• Document public APIs with XML/JSDoc
• Explain "why" not "what"
• Include usage examples
• Keep documentation close to code
• Update docs when code changes

DON'T

• State the obvious
• Leave TODO comments indefinitely
• Write documentation that duplicates code
• Create separate docs that become stale

Comment Types

| Type | When to Use | | ---------------- | ------------------------- | | /// <summary> | Public API documentation | | // Explanation | Complex logic explanation | | // TODO: | Planned improvements | | // FIXME: | Known issues | | // HACK: | Temporary workarounds | | // NOTE: | Important information |

Verification Checklist

• [ ] Public APIs have XML/JSDoc documentation
• [ ] Complex logic has explanatory comments
• [ ] Examples are provided where helpful
• [ ] Documentation is accurate and up-to-date
• [ ] No obvious/redundant comments
• [ ] TODO/FIXME items are actionable

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks
• Always add a final review todo task to verify work quality and identify fixes/enhancements