architecture-review

Use when a dd-trace-js change introduces or substantially changes a class hierarchy, module boundary, shared helper layer, public API, or duplicated behavior across multiple types. Triggers: architecture decision, design review, refactor shared behavior, new abstraction, composition versus inheritance, expose internals, module coupling, public surface, hot-path architecture, score the design.

Quality

90%

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

86%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 lean, well-structured review framework with concrete scoring rules, decision rules, and an output template. Its main gap is the absence of a worked example showing a completed scoring table, which would lift actionability and workflow clarity.

Suggestions

Add one short worked example: a filled-in review table (baseline → proposal scores with evidence) plus the resulting decision, so Claude has a concrete template to mirror.

Make the validation gate in step 5 an explicit re-score loop ('if a blocker dimension regresses, revise the proposal and re-score') to add a feedback loop.

Dimension	Reasoning	Score
Conciseness	The ~75-line body is lean and assumes Claude's competence: each dimension is a few focused sentences ('Behavior shared by multiple types should live in one place'), with no padding or explanation of concepts Claude already knows. It matches anchor 5's 'every token earns its place'.	5 / 5
Actionability	The guidance is concrete and executable for a review skill: score 'from 1–10 on each dimension', 'require the proposal to score at least 8/10 on five dimensions', and an explicit output table. It is not 5 because there is no worked, filled-in example showing a scored review, which is the minor gap anchor 4 describes. Per the scoring notes, absence of code is not penalized for an instruction-only skill.	4 / 5
Workflow Clarity	The Workflow gives a clear 7-step sequence with an explicit validation gate in step 5 ('Require the proposal to score at least 8/10... Treat regressions... as blockers'). It is not 5 because there is no validate→fix→retry feedback loop, though the operation is a review rather than a destructive/batch one so the workflow cap does not apply.	4 / 5
Progressive Disclosure	No bundle files exist and none are needed; the single SKILL.md is well-organized into Workflow, Six Dimensions, Decision Rules, and Review Output sections with no nested references. Per the scoring notes, a focused skill with no need for external references scores 5 with well-organized sections.	5 / 5
	Total	18 / 20 Passed

Description

95%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 specific, well-triggered, and tightly scoped to dd-trace-js architectural changes with a comprehensive trigger list and an explicit 'Use when' clause. The only minor weakness is that the capability ('score the design') trails the trigger list rather than leading it.

Suggestions

Lead with the capability ('Scores proposed dd-trace-js design changes 1–10 across six dimensions') before the 'Use when' clause so the 'what' is as prominent as the 'when'.

Dimension	Reasoning	Score
Specificity	Names the domain (dd-trace-js structural changes) and several concrete situations — 'class hierarchy, module boundary, shared helper layer, public API, or duplicated behavior' — plus the action 'score the design', but does not fully enumerate the review capabilities up front. It sits above anchor 3 (which would list only 1–2 concrete items) but below 5 (which expects comprehensive coverage of the actions).	4 / 5
Completeness	It explicitly answers 'when' with a 'Use when a dd-trace-js change introduces...' clause and answers 'what' with 'score the design' framed by concrete trigger phrases, matching the anchor 5 example that pairs a clear what with an explicit when. It is not a 4 because both halves are present and concretely triggered, not merely implicit.	5 / 5
Trigger Term Quality	The 'Triggers:' list gives comprehensive natural-language coverage a user would actually say: 'architecture decision, design review, refactor shared behavior, new abstraction, composition versus inheritance, expose internals, module coupling, public surface, hot-path architecture, score the design'. This matches the anchor 5 example of thorough natural-term coverage including synonyms.	5 / 5
Distinctiveness Conflict Risk	The skill is tightly scoped to dd-trace-js architecture review with niche-specific triggers (npm-exported Span/Tracer, OpenTelemetry bridge spans, hot-path architecture), giving it a clear niche with minimal conflict risk against general skills. It clearly matches anchor 5's 'clear niche with distinct triggers'.	5 / 5
	Total	19 / 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: DataDog/dd-trace-js
Path: .agents/skills/architecture-review/SKILL.md
Commit: d62655e

Reviewed: 5 days 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.