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

82%

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

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 dense, well-sequenced process skill with a hard human-yes gate, genuine feedback loops, and concrete commands and paths throughout. Its weaknesses are token cost from the ornate prose style and repetition between the procedure and anti-patterns sections, and a broken load-bearing reference: the BRIEF-FORMAT.md file the recording step depends on is missing from the bundle.

Suggestions

Ship BRIEF-FORMAT.md in the skill bundle (or inline the exact shapes of the three writes) so step 5's 'in the shapes [BRIEF-FORMAT.md] gives exactly' resolves — currently the bundle has no references/ or scripts/ directories at all, including the referenced scripts/trace.sh and scripts/agents.config.sh.

Tighten the prose and de-duplicate the yes-gate and convergence rules, which are stated in 'What this skill does not do', step 4, step 5, and Anti-patterns — stating each once and cross-referencing would cut meaningful tokens.

Consider moving the 'Two states to check before starting' and 'Entry points' sections into a short reference file so SKILL.md reads as the procedure plus its guards, keeping the main file leaner.

DimensionReasoningScore

Conciseness

The body is dense and most tokens carry real information (file paths, rules, ordering), but the ornate nested-clause style, rhetorical framing ("This skill is the decision made deliberately, twice"), and rules restated across 'What this skill does not do', steps 4-5, and Anti-patterns (the yes-gate appears four times) mean it could be noticeably tightened.

3 / 5

Actionability

Guidance is largely executable — exact paths (docs/domain-glossary.md, constitution/local-engineering.md), copy-paste trace commands with argument shapes, anchor line labels, commit message format, and temp-file naming — but the actual output shapes are delegated to BRIEF-FORMAT.md, which is absent from the bundle, leaving a gap in the most concrete part of the skill.

4 / 5

Workflow Clarity

Six clearly sequenced steps with an explicit hard validation gate ("Stop here for a human yes before writing anything into the repo") guarding the irreversible write, feedback loops for error recovery (revise-and-present on a no; identical candidates send you back to step 3 with sharper constraints), and edge-case handling (unstamped article, existing brief, single subdomain).

5 / 5

Progressive Disclosure

In-body section structure is good and references are clearly signaled as links, but the load-bearing referenced file BRIEF-FORMAT.md — which step 5 says gives the output shapes 'exactly' — does not exist in the bundle (nor do scripts/trace.sh, scripts/agents.config.sh, or .agents/prompts/cheap-reads.md), and entry-points/two-states detail is inlined in one ~200-line file.

3 / 5

Total

15

/

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.

An exceptionally specific and complete description: concrete actions covering the full read-design-compare-record lifecycle, plus explicit 'use when' triggers with concrete phrases. The only weakness is trigger phrasing that assumes the kit's vocabulary rather than including plain-language synonyms a user might naturally say.

DimensionReasoningScore

Specificity

The description lists 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 comprehensive coverage of the skill's behavior, matching the top anchor rather than the 'minor gaps' anchor below it.

5 / 5

Completeness

It explicitly answers both questions: the 'what' is the full action list, and the 'when' is concrete — "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".

5 / 5

Trigger Term Quality

Triggers like "bootstrap hand-back", "the shape no longer fitting", "style-level red flag", and "architecture" are natural within the kit's domain, but the description leans on kit jargon ("recorded strategic act", "bootstrap hand-back") and offers no plain-language synonyms or variations that anchor 5 requires.

4 / 5

Distinctiveness Conflict Risk

"Design the architecture twice", "context map", and "three anchors" carve a clear niche with no realistic overlap, and the triggers even name the sibling skills (/housekeeping, the architecture skill) that route elsewhere, minimizing wrong-skill triggering.

5 / 5

Total

19

/

20

Passed

Validation

75%

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

Validation — 12 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

metadata_version

'metadata.version' is missing

Warning

relative_links

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

Warning

referenced_paths_exist

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

Warning

Total

12

/

16

Passed

Repository

agranado2k/agentic-sdlc

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.