CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

design-brief

Make the shape of the system a recorded strategic act. Read the brief, the glossary and the decision records, design the architecture twice, compare the candidates on complexity, and — after a human yes — record the paradigm, the architectural style, the context map and the patterns adopted or rejected as three anchors in the engineering article, a glossary section, and one decision record. Use at bootstrap hand-back before the first feature diff, when a planner sees the shape no longer fitting, or when `/housekeeping` or the architecture skill raises a style-level red flag.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

70%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-engineered orchestration skill: the workflow is unambiguous, gated, and rich in feedback loops, with unusually concrete operational parameters (word budgets, file naming, commit format). Its weaknesses are token spend on narrative/philosophical framing and a progressive-disclosure structure that inlines spec detail while depending on a BRIEF-FORMAT.md reference that is absent from the bundle.

Suggestions

Include BRIEF-FORMAT.md in the skill's bundle (or inline its exact anchor/record shapes), since step 5 instructs writing 'in the shapes BRIEF-FORMAT.md gives exactly' and the file is not present alongside SKILL.md.

Trim the narrative opening, the Ousterhout/Evans philosophy paragraph, and the closing attribution footer to rationale-level one-liners; the operational content already carries the procedure.

Move the candidate output specification (the five numbered items plus word budgets in step 3) into a reference file that the spawned subagent prompts cite, keeping SKILL.md as the orchestration overview.

DimensionReasoningScore

Conciseness

The body is mostly efficient — no padding with concepts Claude already knows, and operational details are compressed — but several sections could be tightened: the narrative opening ("Nothing in the chain asked what shape a system is... every later diff conformed to the accident"), the philosophy paragraph defining Ousterhout's strategic programming and Evans's contexts, and the closing attribution footer all spend tokens on justification rather than instruction. This matches anchor 3 (mostly efficient, some tightening possible); it is above 2 because there is no real over-explanation of known material.

3 / 5

Actionability

The guidance is largely executable and specific: hard word budgets ("at most five hundred words", "at most six hundred words", "at most two pages"), a concrete output path pattern ("<tmpdir>/design-brief-<YYYYMMDDTHHMMSSZ>.md" with $TMPDIR fallback), exact anchor lines ("**Paradigm**:", "**Architectural style**:", "**Context map**:"), a commit message format ("docs(design-brief): …"), and named comparison criteria. It misses 5 because step 5 defers the exact output shapes to "the shapes [BRIEF-FORMAT.md](./BRIEF-FORMAT.md) gives exactly" and that file is not in the bundle, leaving the most detail-critical step under-specified as written.

4 / 5

Workflow Clarity

The six-step procedure is clearly sequenced with explicit validation checkpoints and feedback loops: a hard human gate ("Stop here for a human yes before writing anything into the repo"), convergence handling ("Two candidates that agree on paradigm and style have converged... Only two candidates identical on all four points send you back to step 3"), rejection recovery ("If the answer is no... revise and present again"), pre-flight state checks ("Two states to check before starting"), and atomicity of the final writes ("The three writes are one local commit"). This matches the 5 anchor's explicit validation and error-recovery loops.

5 / 5

Progressive Disclosure

In-file structure is good (numbered procedure, entry points, anti-patterns), but the bundle contains no reference files at all: the one detailed reference — ./BRIEF-FORMAT.md, which step 5 depends on for the exact output shapes — is missing from the bundle, and the only other link (../improve-codebase-architecture/INTERFACE-DESIGN.md) points outside the skill. Meanwhile content that could live in a reference (the candidate write-up spec, the record formats) is inlined. This fits anchor 3 (structure present, references not effectively available); it is not 2 because the inline organization is genuinely clear and the body is not a wall of text.

3 / 5

Total

15

/

20

Passed

Description

67%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 dense, information-rich description that explicitly covers what the skill does and when to use it, with concrete actions and named artifacts. Its main weakness is that the trigger vocabulary is kit-internal rather than natural user phrasing, which limits discoverability and leaves the 'when' less explicit for readers outside the kit.

Suggestions

Add natural-language trigger phrases to the 'when' clause — e.g. "use when the user asks to decide or revisit the system's architecture, pick a paradigm or architectural style, or define bounded contexts" — so the skill triggers on what users actually say, not just kit entry points.

Translate or briefly gloss kit-internal terms in the description ("three anchors", "bootstrap hand-back") so the concrete actions read as concrete to a reader without kit context.

State the sibling-skill boundary in one clause (e.g. "shape-level decisions here; interface deepening goes to the architecture skill") to reduce overlap risk with the related architecture skill.

DimensionReasoningScore

Specificity

Quotes multiple concrete actions — "Read the brief, the glossary and the decision records", "design the architecture twice", "compare the candidates on complexity", "record the paradigm, the architectural style, the context map and the patterns adopted or rejected" — with named artifacts (engineering article anchors, glossary section, decision record). It falls short of the 5 anchor because the actions are wrapped in kit-internal vocabulary ("three anchors", "recorded strategic act") that blunts how concrete they read, and well above 2-3 since the coverage of what the skill does is broad and specific.

4 / 5

Completeness

Both questions are explicitly answered: the "what" is a detailed action list, and the "when" is an explicit clause — "Use at bootstrap hand-back before the first feature diff, when a planner sees the shape no longer fitting, or when /housekeeping or the architecture skill raises a style-level red flag". It sits between anchors 4 and 5: the when-clause names three concrete triggers (arguing for 5), but they are couched in project-specific vocabulary rather than trigger phrases a user would actually utter, so the 'when' could be more explicit for an outside reader.

4 / 5

Trigger Term Quality

Relevant keywords are present ("design the architecture", "paradigm", "architectural style", "context map", "decision record", "bootstrap"), but the trigger phrases are kit-internal — "bootstrap hand-back", "when a planner sees the shape no longer fitting", "/housekeeping or the architecture skill raises a style-level red flag" — rather than terms a user would naturally say ("system design", "choose an architecture", "software architecture"). This matches the 3 anchor (some relevant keywords, missing common variations/synonyms); it is not 4 because the natural-language entry points are largely absent.

3 / 5

Distinctiveness Conflict Risk

The niche is clear and specific — deciding and recording system shape into ADR/glossary anchors, explicitly not implementing ("Prefactoring the brief implies goes to /to-tickets") — and it distinguishes itself from the sibling architecture skill ("the architecture skill raises a style-level red flag"). It is not 5 because it is adjacent to that sibling architecture skill and shares trigger surface with /housekeeping, leaving minor overlap risk with closely related kit skills.

4 / 5

Total

15

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 1 possibly missing (./BRIEF-FORMAT.md), 1 suspicious

Warning

referenced_paths_exist

Referenced path issues: 2 possibly missing (scripts/agents.config.sh, scripts/agents.lib.sh)

Warning

Total

14

/

16

Passed

Repository

agranado2k/ai-report-platform

Path

.agents/skills/design-brief/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.