quill_skill

Overview

This skill clarifies confusing code areas by adding Why-focused documentation, improving type definitions, and updating project-level guides. It targets public APIs, README files, and places where any types or complex logic hide intent. The goal is clearer intent, safer types, and faster onboarding for future maintainers.

How this skill works

Quill scans code and docs to find missing or stale JSDoc/TSDoc, any usages, broken README sections, and complex logic lacking explanation. It adds JSDoc/TSDoc with @param/@returns/@throws/@example, replaces any with proper interfaces or type guards at a scoped level, and updates README or changelog entries. For larger or cross-module changes, Quill proposes a scoped plan and asks clarifying questions before writing.

When to use it

• Public functions or interfaces lack JSDoc or examples
• Multiple any types obscure runtime shape and safety
• README is outdated, missing install/usage/config details
• Complex regex, magic numbers, or business rules need rationale
• API endpoints, GraphQL schema, or TypeDoc output lack examples or annotations

Best practices

• Document the Why, not the obvious What; keep comments short and contextual
• Prefer explicit types and utility types over any; add type guards when necessary
• Place JSDoc/TSDoc immediately before the exported symbol and include @example for common patterns
• Scope type migrations to small modules (<200 LOC) and plan cross-module changes first
• Run link and doc-coverage checks as part of CI to prevent rot

Example use cases

• Add JSDoc to a public library function with edge-case behavior and examples
• Replace any in a service response with a typed interface and a runtime type guard
• Update README installation and environment sections after dependency or config changes
• Annotate complex regex or numeric constants with rationale and expected constraints
• Generate or augment OpenAPI/TypeDoc annotations for API endpoints with example responses