Skip to content
Skills Library
Programming · Writing

maintain-jsdocs

/maintain-jsdocs

Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.

Repository
pikacss ↗
Licence
MIT
Last repository change
05.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 05.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.

Original author description

Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.

How it works

  1. Scope
  2. The contract
  3. Workflow
  4. Quality bar
  5. References
Original SKILL.md headings · 80 lines, 507 words
SKILL.md preview
---
name: maintain-jsdocs
description: 'Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps.'
---

# Maintain JSDocs

## Scope

- JSDoc only. README and docs pages are out of scope unless the request says otherwise.
- Covers **all exported declarations** in every source file of a package, not just what `index.ts` re-exports, plus module augmentation members in plugin packages.
- Includes `@internal` exports: gen-api skips them, but their JSDoc is still maintained.
- Excludes `dist/`, `coverage/`, `*.test.ts`, `*.spec.ts`, `pika.gen.*`, `generated-*.ts`.
- English only.

Package directories in this repository: !`grep -o "dir: '[^']*'" "${CLAUDE_PROJECT_DIR}/scripts/_skill-shared/index.ts" | sed "s/dir: //;s/'//g" | tr '\n' ' '`

Ask which packages to process when the request does not say; use `AskUserQuestion` if it is available.

## The contract

`gen-api-docs` extracts JSDoc from `packages/*/src/index.ts` via the TypeScript compiler API. Every gap renders as "Missing JSDoc summary." on a published page, so the gap list is the definition of done:

| Export kind | Required |
|---|---|
| Function | Summary + `@param` description per parameter |
| Interface | Summary + description per property |
| Type alias | Summary |
| Constant / Variable | Summary |
| Class | Summary + description per public property and method, including constructor `@param`s |
| Module augmentation member | Description per property |

`collectCoverageGaps` in `scripts/maintain-docs/gen-api-docs.ts` is the authority. Read it when a gap report is surprising.

## Workflow

1. **Find the gaps.** `pnpm maintain-docs:gen-api` lists every coverage gap by package and symbol. Work from that list.
2. **Write the JSDoc** directly in the source file, reading the implementation and its call sites first.
3. **Validate**:

```bash
pnpm maintain-jsdocs:lint --packages <name>...   # corruption check
pnpm maintain-docs:gen-api                       # zero-gap check
pnpm --filter @pikacss/<name> typecheck
```

Repeat until gen-api reports `✅ No JSDoc coverage gaps detected.`

For large scopes, process one package per subagent in parallel rather than sweeping serially.

### Full restart (opt in, destructive)

`pnpm maintain-jsdocs:scaffold --packages <name>...` **replaces** existing JSDoc on every exported declaration with `@todo FILL:` templates, then you fill each marker and remove the tag.

Use it only when the existing JSDoc for a package is being rewritten wholesale on purpose. It discards good prose along with bad, so gap-driven editing is the default.

## Quality bar

Beyond zero-gap: every sentence must add something the type signature does not already say. "Returns the resolved engine configuration after plugin normalization" over "Returns a ResolvedEngineConfig".

Repo-specific conventions the generator and readers rely on:

- `@default` on every optional interface property — the effective value or behavior when omitted, literals in inline code.
- `@example` with a fenced `ts` block when usage is ordering-sensitive, composable, or easy to misuse.
- `@remarks` for lifecycle, hook interaction, and cross-package relationships — this is where PikaCSS's non-obvious behavior belongs.
- Each JSDoc tag starts its own real line. Never emit literal `\n` or `\t` inside a comment; `maintain-jsdocs:lint` fails on both.

```ts
declare module '@pikacss/core' {
  interface EngineConfig {
    /**
     * CSS reset style injected as a preflight, before utility styles.
     *
     * @default 'tailwind-preflight'
     */
    reset?: ResetStyle
  }
}
```

## References

- [workflow-rules.md](references/workflow-rules.md) — format conventions and the quality checklist.
Files in this package (2)
  • SKILL.md 4 KB
  • references/workflow-rules.md 7 KB

Versions

The database has no other skills named maintain-jsdocs.

Database snapshot: 13.11.2026 · package version a1244b534f76 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 96jsdocs
    Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics.
  • 100write-component-jsdocs
    Guide for writing JSDoc comments on vapor-ui components and their props. Use when adding, reviewing, or fixing JSDoc on component tsx files or css.ts variant files. Covers where to place comments based on component pattern — standalone, compound root, compound sub-part,…
  • 100jsdoc-comment-generator
    Generate jsdoc comment generator operations. Auto-activating skill for Technical Documentation. Triggers on: jsdoc comment generator, jsdoc comment generator Part of the Technical Documentation skill category. Use when working with jsdoc comment generator functionality. Trigger…
  • 100jsdoc
    JSDoc - documentation generator for JavaScript with type annotations. USE WHEN: user mentions "JSDoc", "JavaScript documentation", asks about "documenting JavaScript", "type hints", "jsdoc comments", "API documentation generation" DO NOT USE FOR: TypeScript - use `jsdoc-tsdoc`…
  • 95jsdoc-guide
    JSDoc writing rules for AI-powered documentation generation. Use when writing JSDoc, documenting functions, or adding code comments.
  • 100documentation
    Generate docstrings, JSDoc, API docs, and README updates that reflect current code. Use when: docs, docstring, JSDoc, README, API docs, document this, add documentation.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.