skills.rest
macintorsten
macintorstenCOMMUNITY
Explore all skills by this author →
GitHub

code-documentation

Writes README files, API documentation, inline comments, and architecture decision records for codebases.

Updated Dec 23, 2025
Search Tags:#documentation#openapi#technical writing#adr#readme#code comments#jsdoc
One-click install
npx skills add https://github.com/macintorsten/aurapod --skill code-documentation-macintorsten
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: code-documentation
Source: https://github.com/macintorsten/aurapod/tree/main/.github/skills/code-documentation
Command: npx skills add https://github.com/macintorsten/aurapod --skill code-documentation-macintorsten

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers struggle to produce consistent, maintainable documentation for their codebases, resulting in outdated READMEs, missing API references, and unclear inline comments that slow down onboarding and collaboration. ## Core Features & Use Cases - README Templates: Provides a standard README structure covering quick start, installation, usage, API reference, configuration tables, and licensing. - API Documentation Patterns: Includes JSDoc/TSDoc annotation examples and OpenAPI 3.0 schema definitions for documenting functions, interfaces, and REST endpoints. - Inline Comment Guidelines: Defines when to comment (explaining why, business logic, workarounds) and when not to (stating the obvious, outdated notes). - Architecture Documentation: Supplies ADR (Architecture Decision Record) and component documentation formats with status, context, decision, and consequences sections. - Use Case: When starting a new TypeScript library, use this Skill to generate a complete README, annotate public functions with TSDoc, and record the database choice as an ADR. ## Quick Start Ask the AI to write a README and API documentation for your project following the code-documentation guidelines.

Frequently Asked Questions about code-documentation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a good README for my project?▼

A good README starts with a brief project description, followed by a quick start section with install and run commands. Then add detailed installation, usage examples, an API reference, a configuration table, contributing guidelines, and license information.

How to document a REST API with OpenAPI?▼

Define an OpenAPI 3.0 YAML file with info, paths, and components sections. Each endpoint specifies summary, requestBody, and responses with schema references, while reusable object schemas like UserInput and User live under components/schemas.

When should I write inline comments in code?▼

Write inline comments to explain why a decision was made, clarify complex business logic, or document workarounds and hacks with tracking links. Avoid comments that restate obvious code, and remove outdated comments since they are worse than none.

What is an Architecture Decision Record (ADR)?▼

An ADR is a short document capturing a significant technical decision with sections for status, context, decision, rationale, and consequences. It preserves the reasoning behind choices like database selection so future developers understand the trade-offs.

JSDoc vs OpenAPI for API documentation?▼

JSDoc and TSDoc annotate functions and interfaces directly in source code, suiting library documentation. OpenAPI defines language-agnostic REST API contracts in YAML, suiting HTTP services consumed by external clients.

Related Skills

Explore More Software Engineering Skills→
michael-watsonmichael-watson
8

rpi-research

Analyze codebase architecture, dependencies, and constraints into a research document.

Community
Intermediate
SSiertsemaSSiertsema

documentation-tooling-selection

Evaluate documentation tooling against audience, content, and technical criteria.

Community
Advanced
douglancedouglance
4

documentation

Write and verify README, API, and ADR documentation against shipped code behavior.

Community
Basic
snoodleboot-iosnoodleboot-io

documentation-best-practices

Applies Diátaxis-based patterns to write, structure, and maintain software documentation.

Official
Intermediate