docs_skill

Overview

This skill generates end-user, API, and architecture documentation directly from implemented TypeScript code. It is opinionated for AI-native monorepos using an Express 5 server and CDK for Terraform, and is highly recommended for substantial or public API changes. The goal is durable, accurate docs that reflect what the code actually does.

How this skill works

The skill scans implementation artifacts (source files, tests, and git diffs) to identify public interfaces, endpoints, configuration, and new features. It produces API reference entries, user guides, and architecture documents following project conventions, code examples that compile, and a validation report. It also updates a manifest entry documenting documentation status and logs proof of coverage for atomic specs.

When to use it

• Adding or changing public endpoints, methods, or exported interfaces
• Introducing user-facing features or multi-file services
• Making substantial refactors with behavioral impact or complex logic
• Adding new configuration options or environment variables
• Before merging substantial changes so docs accompany the release

Best practices

• Document the code behavior, not the original spec or internal implementation details
• Include minimal, copy-paste runnable TypeScript examples that import real project types
• Always document error conditions and edge cases for public APIs
• Place artifacts under docs/{api,guides,architecture} and add package READMEs and JSDoc for public exports
• Run quick validation: tsc for examples and prettier for formatting before marking complete

Example use cases

• Generate docs for a new auth API: API reference for endpoints, example requests, and errors
• Create a user guide for a dashboard feature with getting-started steps and troubleshooting
• Produce an architecture doc for a new notification service, including data flow and dependencies
• Document new environment variables and deployment configuration introduced by CDKTF changes
• Add API surface coverage after implementing several exported services in a library package