playbooks

home / skills / plaited / agent-eval-harness / code-documentation@plaited_development-skills

code-documentation@plaited_development-skills skill

/.plaited/skills/code-documentation@plaited_development-skills

This skill provides TSDoc templates and guidelines to write, review, and maintain TypeScript documentation across modules and APIs.

This is most likely a fork of the code-documentation skill from plaited
npx playbooks add skill plaited/agent-eval-harness --skill code-documentation@plaited_development-skills

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
2.2 KB
---
name: code-documentation
description: TSDoc standards for TypeScript/JavaScript code. Automatically invoked when writing, reviewing, or editing any TSDoc comments, code documentation, or API documentation. (project)
license: ISC
compatibility: Requires bun
---

# Code Documentation Skill

## Purpose

This skill provides TSDoc format templates, type documentation guidelines, and maintenance workflows. Use this when:
- Writing or editing TSDoc comments for any function, type, or module
- Reviewing documentation quality
- Creating comprehensive API documentation
- Documenting complex type structures
- Cleaning up non-compliant comments (performance notes, timestamps, inline explanations)
- Synchronizing out-of-sync TSDoc with code changes
- Removing orphaned documentation for deleted code

**Key Standard**: No `@example` sections - tests and stories serve as living examples.

## Quick Reference

- **Creating TSDoc**: See [workflow.md](references/workflow.md) for the generation workflow
- **Maintaining TSDoc**: See [maintenance.md](references/maintenance.md) for cleanup and sync guidelines

This skill contains detailed templates for:
- Public API Functions
- Internal Module Documentation
- Public and Internal Types
- Helper Functions
- Behavioral Programming Functions
- Special Annotations (Security, Performance, Deprecated)
- Type Documentation (Complex Objects, Unions, Functions, Utilities, Branded Types, etc.)

## Navigation

- [workflow.md](references/workflow.md) - TSDoc generation workflow (4 phases)
- [maintenance.md](references/maintenance.md) - Comment policy, sync tasks, orphaned doc handling
- [public-api-templates.md](references/public-api-templates.md) - Templates for public-facing APIs
- [internal-templates.md](references/internal-templates.md) - Templates for internal code and modules
- [type-documentation.md](references/type-documentation.md) - Comprehensive type documentation templates

## Related Skills

- **typescript-lsp**: Use for type verification and discovery during documentation workflow. Essential for Phase 1 (type analysis) and Phase 2 (usage discovery) of the TSDoc generation process. Run `lsp-hover` to verify signatures, `lsp-references` to find usages, and `lsp-symbols` to understand file structure.

Overview

This skill provides TSDoc standards, templates, and workflows for documenting TypeScript and JavaScript projects. It enforces consistent comment structure, handles public and internal API documentation, and outlines maintenance procedures for keeping docs synchronized with code. The standard explicitly avoids @example blocks, relying on tests and stories as living examples.

How this skill works

When invoked during writing, reviewing, or editing TSDoc comments, the skill supplies templates and validation cues tailored to functions, types, modules, and special annotations (security, performance, deprecated). It guides a four-phase generation workflow: type analysis, usage discovery, comment generation, and manual review. It also provides maintenance steps to find orphaned docs and sync comments after code changes.

When to use it

  • Writing new TSDoc for public APIs, internal modules, or complex types
  • Reviewing or editing existing documentation for quality and compliance
  • Documenting complex type structures (unions, branded types, function types)
  • Synchronizing TSDoc after refactors or deleting code to remove orphaned comments
  • Adding special annotations for security, performance, or deprecation

Best practices

  • Prefer concise, factual descriptions; avoid implementation details in comments
  • Do not use @example tags; link to tests or component stories instead
  • Run type discovery (typescript-lsp) to confirm signatures and find usages before writing docs
  • Document intent and behavior for public APIs; document edge cases for internal helpers
  • Keep performance notes and timestamps out of long-lived TSDoc; use maintenance workflows to clean them

Example use cases

  • Generate TSDoc for a new exported function with templates for params, returns, and annotations
  • Audit a module to convert informal inline comments into standardized TSDoc blocks
  • Document a complex union type with examples of discriminants and mapped values in type docs
  • Remove documentation for deleted functions and flag orphaned comments across the codebase
  • Annotate a public API as deprecated with migration guidance and alternative suggestions

FAQ

Why no @example sections?

Examples live in tests and stories to remain executable and up-to-date; documentation links to those living examples instead of duplicating them.

How do I verify signatures before documenting?

Use a TypeScript language server (typescript-lsp) to run hover and references commands to confirm types and find usages as part of the generation workflow.