jsdocs

Write, insert, or update Effect public API JSDoc so it satisfies the jsdocs oxlint rule. Use when adding or fixing JSDoc comments, resolving jsdocs diagnostics, preparing docs for JSON extraction, or reviewing public API documentation.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-structured, highly actionable instruction skill with concrete templates, exact commands, and a clear validated workflow. It respects Claude's intelligence by not re-explaining basics, though some prose rules are repetitive and could be tightened.

Suggestions

Consolidate overlapping prose rules (e.g., several rules about 'When to use' wording) to reduce repetition and tighten the conciseness score.

Consider moving the long 'Prose Rules' and 'Example quality' sections into a separate reference file to improve progressive disclosure and keep SKILL.md as a lean overview.

Add a short 'Quick reference' summary of the required section order and tag order near the top so the most-used facts are discoverable without scrolling the full body.

Dimension	Reasoning	Score
Conciseness	The body assumes Claude's competence (no explanations of what JSDoc or TypeScript are) and is densely prescriptive, but several prose rules are repetitive and could be consolidated. It is efficient overall with minor over-explanation that could be trimmed, matching the 4 anchor rather than a fully lean 5.	4 / 5
Actionability	Provides an exact JSDoc template, concrete commands ("pnpm doctest --run <source files>", "pnpm lint"), explicit tag ordering, and precise required forms ("Use to", "Use when", "Use as", "Use with"). Guidance is copy-paste ready and covers common cases.	5 / 5
Workflow Clarity	The Workflow section gives a clear 5-step sequence ending with "Run the narrowest relevant validation", and the Validation section specifies exact commands and when to run them, forming an explicit validation checkpoint with a feedback loop (run doctest/lint, fix, re-run).	5 / 5
Progressive Disclosure	The skill is a single self-contained SKILL.md with no bundle files (references/, scripts/, assets/ absent) and is organized into well-labeled sections (Workflow, Required documentation shape, Prose Rules, Example quality, Tag rules, Validation). Structure is good and navigation is easy, but the body is fairly long with some content that could be split out, keeping it just below a 5.	4 / 5
	Total	18 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is strong: third-person, concrete, and explicitly paired with a 'Use when' clause covering multiple natural trigger phrases. It is narrowly scoped to Effect public API JSDoc and the jsdocs oxlint rule, minimizing conflict risk.

Dimension	Reasoning	Score
Specificity	"Write, insert, or update Effect public API JSDoc" names the domain plus three concrete actions, and the 'Use when' clause adds further concrete tasks (adding/fixing JSDoc, resolving diagnostics, preparing docs for JSON extraction). Not a 5 because the action list, while several, is not comprehensively exhaustive of every JSDoc-related operation.	4 / 5
Completeness	It explicitly answers what ("Write, insert, or update Effect public API JSDoc so it satisfies the jsdocs oxlint rule") and when ("Use when adding or fixing JSDoc comments, resolving jsdocs diagnostics, preparing docs for JSON extraction, or reviewing public API documentation") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural user-facing phrases such as "adding or fixing JSDoc comments", "resolving jsdocs diagnostics", and "reviewing public API documentation". Good coverage with synonyms, but a few natural variations (e.g. "JSDoc lint errors", "oxlint warnings") are absent, keeping it below 5.	4 / 5
Distinctiveness Conflict Risk	Scoped to "Effect public API JSDoc" satisfying the specific "jsdocs oxlint rule", giving it a clear niche with distinct triggers and minimal overlap with other skills.	5 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: MapleTechLabs/maple
Path: .context/effect/.agents/skills/jsdocs/SKILL.md
Commit: 3cb9193

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.