nodejs-best-practices

Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.

Quality

68%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/nodejs-best-practices/SKILL.md

Quality

Content

80%

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

A lean, highly actionable decision-making skill that uses tables and decision trees to teach Node.js choices without padding — its main gaps are the absence of explicit validation/feedback checkpoints in workflows and a lack of progressive file-splitting for its length.

Suggestions

Add an explicit validate→fix→retry feedback loop for at least one risky area (e.g., after error-handling or validation setup, 'verify with a failing-request test, then fix and re-test') to lift workflow_clarity to 3.

Move the long framework/runtime/library comparison tables into reference files (e.g. references/frameworks.md) and link them one level deep, keeping SKILL.md as an overview to improve progressive_disclosure.

Trim repeated framing ('Teaches thinking, not copying' / 'based on context') which appears across the intro, How-to-Use, Anti-Patterns, and closing sections.

Dimension	Reasoning	Score
Conciseness	The body is table- and ASCII-decision-tree driven, assumes Claude's competence (no 'what is Node.js' or library tutorials), and stays lean with concrete one-liners like 'Never use sync methods in production (fs.readFileSync, etc.)'; only minor restatement keeps it from being perfectly tight but it earns anchor 3.	3 / 3
Actionability	Concrete, decision-enabling guidance throughout — named libraries (Hono/Fastify/Express/Zod/Valibot), a full status-code table, and executable commands ('node --test src/*/.test.ts', 'node file.ts'); as an explicitly instruction/decision skill this meets the actionability bar without copy-paste code.	3 / 3
Workflow Clarity	Useful checklists and flows exist (pre-implementation Decision Checklist, centralized error-handling flow, request-flow tree) but there is no explicit multi-step sequence with validation/feedback checkpoints for risky operations, leaving it at anchor 2.	2 / 3
Progressive Disclosure	The skill is well-organized into numbered sections with no nested/broken references, but at ~330 lines it is a single monolithic file with detailed comparison tables and decision trees that could be split into reference files, matching anchor 2's 'content that should be separate is inline'.	2 / 3
	Total	10 / 12 Passed

Description

57%

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 clearly identifies its Node.js niche and several specific sub-topics, but it answers only 'what' — explicit 'when to use' trigger guidance is absent from the description field itself, capping completeness and trigger quality at the midpoint.

Suggestions

Fold the trigger guidance into the description itself, e.g. '…Use when building Node.js backends, selecting between Express/Fastify/NestJS/Hono, or implementing async/validation/security patterns.' so completeness can reach 3.

Lead with concrete verbs ('Select frameworks, structure layered architectures, choose async patterns, harden security') rather than abstract nouns ('principles and decision-making') to lift specificity.

Add natural user phrasings ('Node.js backend', 'which framework should I use', 'async vs promises') to broaden trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Names the Node.js domain and enumerates specific sub-areas ('Framework selection, async patterns, security, and architecture'), but these are topic areas rather than concrete verbs/actions like 'extract… fill… merge', so it falls short of the multi-action anchor 3.	2 / 3
Completeness	The description clearly answers 'what' but contains no explicit 'Use when…' trigger clause — that guidance lives in a separate when_to_use field — so per the rubric guideline completeness is capped at 2.	2 / 3
Trigger Term Quality	Real relevant keywords appear ('Node.js', 'framework', 'async patterns', 'security'), but the phrasing leans toward topic jargon ('decision-making', 'architecture') and lacks the breadth of natural user phrasings that would warrant anchor 3.	2 / 3
Distinctiveness Conflict Risk	The niche is clearly scoped to Node.js backend development with distinct sub-domains (framework selection, async, security), making it unlikely to trigger for unrelated skills.	3 / 3
	Total	9 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: vudovn/ag-kit
Path: .agents/skills/nodejs-best-practices/SKILL.md
Commit: 04514f0

Reviewed: about 12 hours 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.