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

86%

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

SKILL.md
Quality
Evals
Security

Quality

Content

77%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 tightly written orchestration skill with an exemplary gated workflow — explicit human checkpoint, convergence feedback loops, and concrete paths, caps, and output labels throughout. Its weaknesses are confined to packaging: a ~190-line monolithic body whose single load-bearing reference (BRIEF-FORMAT.md) is missing from the bundle, leaving the exact artifact shapes unspecified, plus a few passages of motivational and vocabulary context that could be trimmed.

Suggestions

Ship BRIEF-FORMAT.md with the skill (or inline its exact anchor/record shapes into SKILL.md) — step 5's precision currently depends on a file that does not exist in the bundle.

Move the stable, non-procedural material — the Ousterhout/Evans vocabulary mapping, the entry-point catalog, and the subdomain-classification definitions — into a one-level-deep reference file so the procedure in SKILL.md reads leaner.

Trim the opening "accident" narrative and the closing provenance footnote to a sentence each; both restate motivation the description already carries.

DimensionReasoningScore

Conciseness

The body is dense and mostly operational — word caps ("at most five hundred words", "at most six hundred words", "at most two pages"), exact file paths, and precise output shapes dominate over filler. Minor trimmable material remains: the opening "accident" narrative, the in-line definition of Ousterhout's complexity vocabulary and Evans's DDD mapping, and the closing provenance footnote. Not 5: these passages explain context Claude could be trusted to infer; not 3: almost every sentence carries a constraint or instruction.

4 / 5

Actionability

For an instruction-only skill the guidance is highly concrete: exact paths (`docs/domain-glossary.md`, `docs/adr/`, `constitution/local-engineering.md`, `scripts/agents.config.sh`), temp-file naming `<tmpdir>/design-brief-<YYYYMMDDTHHMMSSZ>.md`, exact anchor labels (`**Paradigm**:`, `**Architectural style**:`, `**Context map**:`), a five-item candidate spec, and a commit prefix `docs(design-brief): …`. The gap: step 5 delegates the exact artifact shapes to `BRIEF-FORMAT.md`, which is not present in this bundle, so the copy-paste-precise output formats are unreachable.

4 / 5

Workflow Clarity

Six numbered steps in a clear sequence with explicit validation checkpoints and feedback loops: a hard stop ("Stop here for a human yes before writing anything into the repo"), a convergence check that scopes or restarts the comparison ("Only two candidates identical on all four points send you back to step 3"), recovery on rejection ("revise and present again"), pre-flight states to check, and the three writes bound into one reviewable commit. This matches the score-5 anchor including error-recovery loops.

5 / 5

Progressive Disclosure

The body is a well-sectioned but ~190-line single file with no bundle present, and its one format-critical reference — "in the shapes [BRIEF-FORMAT.md](./BRIEF-FORMAT.md) gives exactly" — does not resolve to a real file in this bundle, nor does the cross-skill `../improve-codebase-architecture/INTERFACE-DESIGN.md` link. The reference is clearly signaled (arguing against a lower score), but navigation fails exactly where the output precision matters, and content like the candidate spec and entry-point catalog lives inline. Not 4: a dangling load-bearing reference plus the absence of any working split is more than a minor organization gap.

3 / 5

Total

16

/

20

Passed

Description

92%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, explicit description that clearly answers both what the skill does and when to use it, with concrete enumerated actions and multiple named trigger conditions. Its only weakness is that the trigger vocabulary is kit-internal ("bootstrap hand-back", "style-level red flag") rather than the phrases a user would naturally volunteer, costing it synonym coverage.

DimensionReasoningScore

Specificity

The description enumerates 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 as three anchors … a glossary section, and one decision record" — comprehensively covering the skill's procedure. Not 4: there are no coverage gaps; the only abstract phrase ("a recorded strategic act") is a purpose statement, not a substitute for action.

5 / 5

Completeness

Both halves are explicit: a full "what" (read → design twice → compare → record three anchors, a glossary section, and one decision record after a human yes) and a concrete "when" 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"). This matches the score-5 anchor exactly.

5 / 5

Trigger Term Quality

Trigger coverage is good and explicit — "bootstrap hand-back before the first feature diff", "when a planner sees the shape no longer fitting", "`/housekeeping` or the architecture skill raises a style-level red flag" — but the phrasing is kit-internal jargon and lacks natural synonyms a user might say (e.g., "architecture decision", "system shape", "tech choices"). Not 5: no synonym/variation coverage; not 3: several distinct, genuinely matchable trigger phrases are present.

4 / 5

Distinctiveness Conflict Risk

It carves a clear niche — deciding and recording the system's shape — and explicitly disambiguates from sibling skills (`/to-tickets` for prefactoring, `/improve-codebase-architecture` for deepenings, `/housekeeping` as an entry point that reopens the brief). Trigger conditions are specific enough that it is unlikely to fire for the wrong skill.

5 / 5

Total

19

/

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/tic-tac-toe-haskell

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.