{"id":47621799,"url":"https://github.com/jbelew/agentic-jsdoc","last_synced_at":"2026-04-01T22:18:28.725Z","repository":{"id":346021355,"uuid":"1188182582","full_name":"jbelew/agentic-jsdoc","owner":"jbelew","description":"Writes and reviews JSDoc optimized for LLM parsing, maximizing agentic RAG retrieval and architecture comprehension.","archived":false,"fork":false,"pushed_at":"2026-03-22T01:13:37.000Z","size":142,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T10:29:15.326Z","etag":null,"topics":["agent-skill","documentation","jsdoc","react","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbelew.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T18:18:00.000Z","updated_at":"2026-03-22T01:13:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jbelew/agentic-jsdoc","commit_stats":null,"previous_names":["jbelew/agentic-jsdoc"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/jbelew/agentic-jsdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbelew%2Fagentic-jsdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbelew%2Fagentic-jsdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbelew%2Fagentic-jsdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbelew%2Fagentic-jsdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbelew","download_url":"https://codeload.github.com/jbelew/agentic-jsdoc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbelew%2Fagentic-jsdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","documentation","jsdoc","react","typescript"],"created_at":"2026-04-01T22:18:25.677Z","updated_at":"2026-04-01T22:18:28.711Z","avatar_url":"https://github.com/jbelew.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"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 `@param`, `@returns`, `@throws`, `@category`, `@example`, and `{@link path/to/file Label}` 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 `eslint-plugin-jsdoc` rules.\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,ts,tsx}\"],\n    plugins: { jsdoc },\n    settings: {\n      jsdoc: {\n        mode: \"typescript\",\n      },\n    },\n    rules: {\n      // Force JSDoc on functions, classes, and crucially: React components/hooks (VariableDeclarations)\n      \"jsdoc/require-jsdoc\": [\"warn\", {\n        require: { FunctionDeclaration: true, MethodDefinition: true, ClassDeclaration: true },\n        contexts: [\"TSInterfaceDeclaration\", \"TSTypeAliasDeclaration\", \"ExportNamedDeclaration \u003e VariableDeclaration\", \"Program \u003e VariableDeclaration\"],\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\"]\n      }],\n      // Enforce {@link} instead of Markdown links for cross-references\n      \"jsdoc/no-undefined-types\": [\"warn\", { \"definedTypes\": [\"JSX\"] }],\n    },\n  },\n]);\n```\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, missing `@param`/`@returns` types, and the new `@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`, `{any}`/`{*}` types, void hooks without `@returns {void}`, 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbelew%2Fagentic-jsdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbelew%2Fagentic-jsdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbelew%2Fagentic-jsdoc/lists"}