{"id":"0216e170-1ae9-4b4b-b723-60ab46b32d97","slug":"agentic-jsdoc","kind":"skill","name":"agentic-jsdoc","summary":"Writes and reviews JSDoc optimized for LLM parsing, maximizing agentic RAG retrieval and architecture comprehension.","owner":"jbelew","repoUrl":"https://github.com/jbelew/agentic-jsdoc","license":"AGPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-03-21T18:18:00.000Z","addedAt":"2026-10-21T12:48:56.992Z","logoUrl":"https://avatars.githubusercontent.com/u/4211774?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","memory-knowledge","writing"],"tags":["documentation","jsdoc","react","typescript"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T14:13:58.291Z","sample":false,"url":"https://conduits.dev/tools/agentic-jsdoc","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Agentic JSDoc: Enhanced JSDoc Patterns for LLM Workflows\n\nAn Agent Skill providing a set of JSDoc patterns designed to improve Large Language Model (LLM) comprehension for code generation, documentation, and RAG (Retrieval-Augmented Generation) retrieval.\n\nWhen an LLM agent creates or reads code without a clear convention, it often misses critical architecture links and struggles with React edge cases. This skill guides the agent to document React context hooks, Zustand stores, Suspense boundaries, and explicit routing.\n\n## The Patterns ([SKILL.md](./SKILL.md))\n\nThe core of this project is [SKILL.md](./SKILL.md). It provides a set of patterns for your AI agent to follow:\n- **Priority Tags**: Recommended usage of `@remarks`, `@param`, `@returns`, `@throws`, `@category`, `@example`, and `{@link SymbolName}` for RAG clarity.\n- **Hierarchical Structure**: A deterministic block order (Summary → `@remarks` → Tags → Example) to improve LLM parsing and TypeDoc compatibility.\n- **Architecture Primitives**: Specialized JSDoc patterns for React Components, Custom Hooks, Zustand Stores, and Zod Schemas.\n- **Review Criteria**: A built-in guide for agents to audit and refactor existing documentation.\n\nYour agent will automatically ingest `SKILL.md` when installed as a skill, providing persistent grounding for all documentation tasks.\n\n## Installation\n\nInstall this skill automatically into your project using the `skills` CLI:\n\n```bash\nnpx skills add jbelew/agentic-jsdoc\n```\n\nAlternatively, you can add it to your local environment manually by cloning it into your skills directory:\n\n```bash\nmkdir -p .agents/skills\ngit clone https://github.com/jbelew/agentic-jsdoc.git .agents/skills/agentic-jsdoc\n```\n\n## Linting Enforcement\n\nTo help your team naturally adhere to these patterns before an LLM even touches the codebase, you can use these recommended `eslint-plugin-jsdoc` rules.\n\n> [!IMPORTANT]\n> **Anti-Artifact Fix:** Always disable the JSDoc fixer by setting `fixer: { enable: false }`. If enabled, ESLint will insert empty `/** * */` blocks during `--fix` runs, which creates noise for LLMs and consumes unnecessary tokens. You want the linter to warn you about missing docs so you (or your agent) can write meaningful ones.\n\nAdd this to your ESLint configuration (`eslint.config.js`):\n\n```javascript\nimport jsdoc from \"eslint-plugin-jsdoc\";\nimport { defineConfig } from \"eslint/config\";\n\nexport default defineConfig([\n  {\n    files: [\"**/*.{js,jsx,ts,tsx}\"],\n    plugins: { jsdoc },\n    settings: {\n      jsdoc: {\n        mode: \"typescript\",\n      },\n    },\n    rules: {\n      // Force JSDoc on functions, classes, interfaces, types, and top-level declarations\n      \"jsdoc/require-jsdoc\": [\"warn\", {\n        fixer: { enable: false }, // Prevent empty JSDoc artifacts\n        require: { FunctionDeclaration: true, MethodDefinition: true, ClassDeclaration: true },\n        contexts: [\n          \"TSInterfaceDeclaration\", \n          \"TSTypeAliasDeclaration\", \n          \"ExportNamedDeclaration[declaration.type='VariableDeclaration']\", \n          \"ExportDefaultDeclaration\",\n          \"Program > VariableDeclaration\"\n        ],\n      }],\n      \"jsdoc/require-param-description\": \"warn\",\n      \"jsdoc/require-returns-description\": \"warn\",\n      \"jsdoc/require-example\": \"warn\",\n      \"jsdoc/require-description\": \"warn\",\n      \"jsdoc/check-tag-names\": [\"warn\", {\n        definedTags: [\"hook\", \"component\", \"remarks\", \"performance\", \"accessibility\", \"security\", \"category\"],\n      }],\n      \"jsdoc/sort-tags\": [\"warn\", {\n        tagSequence: [\n          { tags: [\"remarks\"] },\n          { tags: [\"typedef\"] },\n          { tags: [\"template\"] },\n          { tags: [\"param\"] },\n          { tags: [\"returns\"] },\n          { tags: [\"throws\"] },\n          { tags: [\"deprecated\"] },\n          { tags: [\"default\"] },\n          { tags: [\"see\"] },\n          { tags: [\"hook\", \"component\"] },\n          { tags: [\"category\"] },\n          { tags: [\"example\"] },\n        ],\n      }],\n    },\n  },\n  {\n    // In TypeScript, rely on the AST for types and forbid redundant {type} annotations on @param/@returns\n    files: [\"**/*.{ts,tsx}\"],\n    plugins: { jsdoc },\n    rules: {\n      \"jsdoc/no-types\": \"warn\",\n    },\n  },\n  {\n    // In plain JavaScript, require explicit TypeScript-flavor {type} annotations\n    files: [\"**/*.{js,jsx}\"],\n    plugins: { jsdoc },\n    rules: {\n      \"jsdoc/require-param-type\": \"warn\",\n      \"jsdoc/require-returns-type\": \"warn\",\n      \"jsdoc/no-undefined-types\": \"warn\",\n    },\n  },\n]);\n```\n\n### Tag Philosophy: Why this order?\n\nThe hierarchical order in `jsdoc/sort-tags` is designed for **Agentic Retrieval**:\n\n*   **`@remarks` First**: Putting the \"Why\" before the \"How\" (params) helps agents understand architectural intent before getting bogged down in implementation details.\n*   **`@example` Last**: Keeping the example at the bottom provides a \"clean exit\" for RAG (Retrieval-Augmented Generation) systems, ensuring the code snippet is captured in its entirety without being interleaved with metadata.\n*   **Context Selectors**: Standard JSDoc linting often misses React components defined as arrow functions. The `ExportNamedDeclaration[declaration.type='VariableDeclaration']` selector ensures these critical UI primitives are always documented.\n\n## Lessons from the Field\n\nThis project follows an \"eat your own dog food\" philosophy. During a large-scale migration of the [NMS Technology Optimizer](https://github.com/jbelew/nms_optimizer-web), we discovered that automated `--fix` runs were generating hundreds of empty JSDoc blocks. This led to the discovery of the `fixer: { enable: false }` requirement, which is now a foundational recommendation of this skill.\n\n## Strict TypeDoc Generation\n\nBecause these patterns encourage rich metadata tags and explicit linking, the codebase becomes fully compatible with automatic wiki generators natively. You can drop in `typedoc` and it will read these structured comments flawlessly!\n\n```bash\nnpm install -D typedoc\nnpx typedoc --entryPointStrategy expand --entryPoints src/ --exclude \"**/*.test.*\" --exclude \"**/*.stories.*\" --out docs/api --tsconfig tsconfig.json\n```\n\n## Examples Directory\n\nThis skill ships with an `examples/` directory that provides exact 1-to-1 examples of how architecture elements should be fully documented for maximum agent comprehension. The agent can use these files as grounding truth.\n\n## Testing the Skill\n\nThe `tests/` directory contains a fixture for smoke-testing the skill after changes.\n\n### Test 1: `@see` conventions and structure (review mode)\n\n1. Load the skill: `Load agentic-jsdoc`\n2. Ask: `Review the JSDoc in tests/test_fixture.tsx`\n3. Compare against `tests/test_fixture.expects.md`\n\nCovers `@see` consistency, proper use of `{@link}` vs Markdown links, `@typedef` redundancy, boilerplate component `@param`/`@returns` tags, and `@remarks`, `@hook`, and `@component` requirements. Expects 8 violations flagged and 3 correct usages left alone.\n\n### Test 2: Tag-specific rules (review mode)\n\n1. Load the skill: `Load agentic-jsdoc`\n2. Ask: `Review the JSDoc in tests/test_fixture_tags.tsx`\n3. Compare against `tests/test_fixture_tags.expects.md`\n\nCovers `@deprecated` without migration path, missing `@throws`, redundant/vague `{any}`/`{*}` types, void hooks without `@returns Side-effects only.`, and missing `@remarks` or `@hook` tags. Expects 5 violations flagged.\n\n### Test 3: Writing JSDoc from scratch (write mode)\n\n1. Load the skill: `Load agentic-jsdoc`\n2. Ask: `Write JSDoc for every export in tests/test_fixture_write.tsx`\n3. Compare against the checklist in `tests/test_fixture_write.expects.md`\n\nCovers a bare file with no JSDoc across a component, context hook, Zod schema, utility function, and side-effect hook. Verifies the agent produces correct hierarchical structure, proper `@see` link styles, and complete tag coverage.\n"}