CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/architecture-review/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

67%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.

A well-structured, actionable instruction-only skill with concrete decision rules tailored to dd-trace-js and a clear output format. Its weaknesses are moderate redundancy in the score-philosophy caveats and the absence of a worked scoring example that would make the workflow fully concrete.

Suggestions

Consolidate the three repeated score-philosophy caveats (intro, workflow step 5, Review Output) into a single statement, removing the duplicated reject-complexity rule.

Include one short worked example of a filled-in baseline → proposal scoring table so the workflow's output format is unambiguous in practice.

Name the concrete validation actions expected before merging (e.g. which observable tests or benchmarks to run) instead of referring only to 'the validation needed'.

DimensionReasoningScore

Conciseness

The body is mostly tight and repo-specific, but the same caveat is padded in three places ("The score is a decision aid, not a substitute for reasoning", "Use the scores to expose trade-offs, not as a pass/fail threshold", "The score and table are planning aids"), and the reject-complexity rule appears both in the intro and in workflow step 5. This matches 'mostly efficient but could be tightened' rather than the minor-trims level.

3 / 5

Actionability

As an instruction-only skill it gives concrete, specific guidance: a seven-step workflow, six defined dimensions, decision rules with concrete thresholds ("at most two sibling types share a complete interface contract", "a `7 → 7` rewrite is not architectural progress"), and a ready-to-use output table. A worked example with filled-in scores would close the remaining gap, so it is 'mostly executable' rather than fully so.

4 / 5

Workflow Clarity

The seven-step workflow is clearly sequenced with checkpoints for user escalation ("Ask the user before implementation when two viable designs have meaningful trade-offs") and test coverage ("cover boundaries with observable tests"), and the output section requires stating "the validation needed before merging". No destructive or batch operations apply, so no cap; the residual gap is that validation is named rather than specified as an explicit validate-and-recover loop.

4 / 5

Progressive Disclosure

No references/, scripts/, or assets/ bundle exists, and none is needed — the skill is a single-purpose, self-contained review checklist with well-organized sections (Workflow, Six Dimensions, Decision Rules, Review Output) and easy navigation. At ~80 lines it exceeds the under-50-line simple-skill case, so it earns the good-structure anchor rather than the top one.

4 / 5

Total

15

/

20

Passed

Description

73%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.

A highly targeted, well-triggered description for a repo-specific architecture review skill. Its main weakness is that the skill's actual function (structured review with six-dimension baseline-vs-proposal scoring) is never stated directly — the reader must infer it from trigger terms.

Suggestions

Open with a one-sentence statement of what the skill does (e.g. 'Reviews and scores proposed structural changes in dd-trace-js against a six-dimension baseline-vs-proposal rubric.') before the 'Use when' clause.

Add a few natural trigger variations users might say, such as 'refactor shared code', 'design doc', or 'API surface change', to broaden natural-term coverage.

DimensionReasoningScore

Specificity

The description names the domain precisely ("class hierarchy, module boundary, shared helper layer, public API, or duplicated behavior across multiple types") but states few concrete actions — what the skill does only surfaces indirectly via the triggers "design review" and "score the design". It matches the anchor of a clear domain with 1-2 concrete actions rather than the level-4 list of several specific actions.

3 / 5

Completeness

The 'when' is explicit and concrete ("Use when a dd-trace-js change introduces or substantially changes...") so the missing-trigger cap does not apply, and a 'what' (architectural design review and scoring) is present but only implied through the trigger list. It sits between the clear-what/weak-when anchor (3) and the fully-explicit-both anchor (5), landing at 4.

4 / 5

Trigger Term Quality

"architecture decision, design review, refactor shared behavior, new abstraction, composition versus inheritance, expose internals, module coupling, public surface, hot-path architecture, score the design" gives good, natural keyword coverage a user would plausibly say. A few common variations (e.g. "refactor", "design doc", "API surface change") are absent, so it stops short of the comprehensive-synonyms anchor.

4 / 5

Distinctiveness Conflict Risk

Scoping to "dd-trace-js" structural changes with distinct triggers ("composition versus inheritance", "hot-path architecture", "expose internals") carves out a clear niche with minimal overlap risk against generic code-review or bug-fix skills, matching the clear-niche anchor.

5 / 5

Total

16

/

20

Passed

Validation

100%

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

Reviewed

Table of Contents

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.