CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

adr-writer

Cria Architecture Decision Records (ADRs) para decisões técnicas. Inclui alternativas, justificativa e consequências.

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 ./skills/workflow/adr-writer/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

78%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 lean, well-structured single-file skill with concrete rules, a clear sequenced decision-making process, and an appropriate scope for inline content. The main gaps are duplicated when-to-use conditions across two sections, a template compressed into a run-on paragraph rather than a copy-paste-ready block, and the absence of a final validation step.

Suggestions

Merge "Purpose" and "When to Use" into a single section to eliminate the duplicated trigger conditions (trade-off, multiple options, future impact) and free tokens.

Rewrite the Template as a fenced markdown template block with the ADR headings on separate lines so it is copy-paste ready rather than a dense run-on paragraph.

Add a final validation step to the Process (e.g., "Step 5 — Verify the ADR satisfies Rules 1-5: at least 2 alternatives, rejection reasons, both positive and negative consequences, and the correct status") to give the workflow an explicit checkpoint.

DimensionReasoningScore

Conciseness

The body is lean with no explanations of concepts Claude already knows, but the "Purpose" and "When to Use" sections duplicate the same trigger conditions (trade-off exists, multiple viable options, future impact) and the mission line "This skill makes decisions explicit, documented, and reviewable" could be trimmed. This matches anchor 4 — efficient with minor instances that could be tightened — rather than the every-token-earns-its-place level of anchor 5.

4 / 5

Actionability

Concrete guidance throughout: an explicit output path (spec/90-decisions/ADR-XXXX-<slug>.md), hard rules (at least 2 alternatives, rejection reasons, consequences, PROPOSED vs ACCEPTED), and a fully numbered 5-step process. The main gap is that the Template is compressed into a single dense run-on paragraph instead of a copy-paste-ready markdown block, which keeps it below anchor 5.

4 / 5

Workflow Clarity

Steps 0-4 are explicitly sequenced (decision statement → gather options → evaluation criteria → choose + justify → consequences) and the conditional status rule (unknowns → PROPOSED) adds a built-in check. However, there is no explicit validation checkpoint such as verifying the drafted ADR satisfies all Rules before finishing, so it fits anchor 4 rather than 5.

4 / 5

Progressive Disclosure

The body is roughly 41 non-blank lines, no bundle files (references/, scripts/, assets/) exist or are needed, and there are no nested references. Sections (Purpose, When to Use, Output Files, Rules, ADR Statuses, Process, Template) are well-organized, which per the rubric guideline earns a 5 for a short single-file skill.

5 / 5

Total

17

/

20

Passed

Description

65%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 concise, states a clear "what", and occupies a distinctive niche, but it omits any explicit when-to-use guidance (deferring that to the frontmatter `triggers` field) and covers only a narrow slice of the skill's capabilities. Trigger coverage of the core ADR terminology is good, though natural variations like "trade-off" and "design decision" are missing.

Suggestions

Add an explicit "Use when..." sentence to the description itself (e.g., "Use when documenting design trade-offs, architecture choices, or decisions about storage, auth, or inter-service communication"), which would lift completeness from the capped 3.

Include natural trigger variations such as "trade-off", "design decision", or "technical decision record" in the description text, since users needing this skill may phrase the request in those terms rather than saying "ADR".

Broaden the "what" with one or two more concrete actions (e.g., "documents evaluation criteria, rejected alternatives, and consequences using a standard ADR template") to move specificity beyond domain-plus-1-2-actions.

DimensionReasoningScore

Specificity

"Cria Architecture Decision Records (ADRs)" names the domain and action, and "Inclui alternativas, justificativa e consequências" lists 2-3 concrete content elements, but this stays at the anchor-3 level of domain plus a couple of actions rather than several specific actions with broad coverage.

3 / 5

Completeness

The "what" is clear (creates ADRs that include alternatives, justification, and consequences), but the description itself contains no "Use when..." clause or equivalent explicit trigger guidance — that lives in the separate frontmatter `triggers` field. Per the judging guideline, a missing use-when clause caps completeness at 3.

3 / 5

Trigger Term Quality

The description includes the full term "Architecture Decision Records", the acronym "ADRs", and "decisões técnicas" — good natural-keyword coverage of the core concept. It misses common variations such as "trade-off", "design decision", or "decision record", so it does not reach comprehensive anchor-5 coverage.

4 / 5

Distinctiveness Conflict Risk

ADR authoring is a clear niche with distinct triggers; "Architecture Decision Records (ADRs) para decisões técnicas" is unlikely to fire for unrelated skills, matching the anchor-5 example of a clear niche with minimal conflict risk.

5 / 5

Total

15

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

fernandezbaptiste/cursor-multiagent-system

Path

skills/workflow/adr-writer/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.