skills.rest
taxmaxi
taxmaxiOFFICIAL
Explore all skills by this author →
Website𝕏@TaxMaxiHQGitHub

jsdocs

Writes and updates Effect public API JSDoc to satisfy the jsdocs oxlint rule.

1|1|Updated May 11, 2026
Search Tags:#typescript#documentation#jsdoc#api docs#effect#doctest#oxlint
One-click install
npx skills add https://github.com/taxmaxi/taxmaxi --skill jsdocs-taxmaxi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: jsdocs
Source: https://github.com/taxmaxi/taxmaxi/tree/main/repos/effect/.agents/skills/jsdocs
Command: npx skills add https://github.com/taxmaxi/taxmaxi --skill jsdocs-taxmaxi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Public API documentation in the Effect codebase must follow a strict JSDoc structure enforced by a custom oxlint rule, and writing or fixing these comments by hand is error-prone. This Skill guides the AI to produce compliant JSDoc, resolve jsdocs diagnostics, and prepare docs for JSON extraction. ## Core Features & Use Cases - Standardized Documentation Shape: Enforces the required template with short description, optional When to use, Details, and Gotchas sections, plus titled Example blocks and ordered tags like @category and @since. - Module Refinement Audits: Runs dedicated @see and Gotchas audits across a module to keep cross-references and caveats accurate and useful. - Executable Examples: Supports import.meta.vitest runnable examples validated with pnpm doctest, keeping documentation examples deterministic and tested. - Use Case: When adding a new public function to an Effect module, use this Skill to write compliant JSDoc with a runnable example, then validate it with pnpm lint and pnpm doctest. ## Quick Start Ask the AI to write or fix the JSDoc for a specific Effect public API so it passes the jsdocs lint rule.

Frequently Asked Questions about jsdocs

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

FAQPage Schema
How do I write JSDoc for Effect public APIs that passes the jsdocs lint rule?▼

Write a multiline JSDoc comment with a one-paragraph short description, optional When to use, Details, and Gotchas sections in that order, titled Example blocks with ts code fences, and ordered tags ending with @category and @since. Then run pnpm lint to verify compliance.

How do I fix jsdocs diagnostics in the Effect repository?▼

Inspect the declaration, implementation, and nearby tests, then rewrite the comment into the required documentation shape while preserving correct facts and examples. Run pnpm lint afterward, since the linter includes the custom rule that checks public API JSDoc.

What sections are allowed in Effect public API JSDoc?▼

Only the standard sections are allowed: When to use, Details, and Gotchas, in that fixed order, plus Example sections with unique titles. Markdown headings and ad hoc bold headings like Notes are not permitted.

How do I run executable JSDoc examples in Effect?▼

Mark runnable TypeScript fences with import.meta.vitest and execute them from the repository root with pnpm doctest --run followed by the source files. Each example must be a complete, deterministic, self-contained module.

When should I add @see tags and Gotchas sections to API docs?▼

Add @see tags only for semantically related public APIs such as siblings, alternatives, or inverse operations, and add Gotchas only for concrete caveats like edge cases or surprising behavior. During module refinement, run dedicated @see and Gotchas audits before finishing.

Related Skills

Explore More Software Engineering Skills→
sciman-topsciman-top

draft-spec

Drafts review-ready Markdown specifications from conversation and repository context without publishing.

Community
Basic
Lin117-shygoLin117-shygo

finish-work

Run pnpm lint, type-check, and test before commit.

Community
Intermediate
legioncodeinclegioncodeinc
84

api-docs-stinger

Generates API documentation, SDKs, and changelogs from OpenAPI specifications.

Official
Advanced
MapleTechLabsMapleTechLabs
1.6k

jsdocs

Writes compliant JSDoc for Effect public APIs to pass jsdocs oxlint rule.

Official
Intermediate