CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architectural-proposals

How to write comprehensive architectural proposals that drive alignment before code is written

Quality

73%

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 ./.squad/templates/skills/architectural-proposals/SKILL.md

The canonical home for this skill is architectural-proposals in bradygaster/squad

SKILL.md
Quality
Evals
Security

Quality

Content

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

The content is highly actionable and well-structured with concrete formats and worked examples, penalized only mildly for some redundancy between Patterns and Anti-Patterns and the absence of an explicit pre-publish validation checkpoint.

Suggestions

Add an explicit validation/review checkpoint (e.g., a proposal self-review checklist verifying each required section is present and risks have mitigations) before sign-off, to strengthen workflow_clarity.

Reduce redundancy between the 'Tone Ceiling Enforcement'/'Never' list and the 'Anti-Patterns' red-flags list by consolidating them.

Consider extracting the required-sections template and risk/decision formats into a referenced template file (e.g., references/proposal-template.md) to improve progressive_disclosure and reduce inline length.

DimensionReasoningScore

Conciseness

The body is dense and operational with no basic-concept filler, but the Anti-Patterns section restates the Patterns 'Never' items and the 10-point 'Key patterns demonstrated' list is somewhat padded, fitting anchor 4 (efficient with minor trims possible) rather than 5.

4 / 5

Actionability

It provides fully executable, copy-paste-ready structures: enumerated required sections, a decision-framing format with a worked example, a risk-documentation format with a full example, and a wave-restructuring pattern covering the common cases, matching anchor 5.

5 / 5

Workflow Clarity

The 7-step 'Key patterns demonstrated' sequence and the 4-step wave-restructuring process give a clear sequence, but there is no explicit validation/review checkpoint or feedback loop before publishing the proposal, which holds it below anchor 5.

4 / 5

Progressive Disclosure

Sections are well-organized (Context, Patterns, Examples, Anti-Patterns) and the skill is self-contained with no bundle files, but ~130 lines of inlined templates could plausibly split into a separate proposal-template reference file, fitting anchor 4 rather than 5.

4 / 5

Total

17

/

20

Passed

Description

53%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 clearly identifies a specific niche and purpose but lacks an explicit 'when to use' trigger clause and a broader set of concrete actions or trigger synonyms, which caps completeness and trigger_term_quality at 3.

Suggestions

Add an explicit 'Use when...' clause listing concrete triggering situations (e.g., architecture shifts, product direction changes, multi-wave decisions, dependency changes).

Broaden trigger-term coverage with synonyms users would naturally say (e.g., 'RFC', 'design doc', 'architecture decision record', 'technical proposal').

Enumerate 2-3 specific concrete actions the skill performs (e.g., 'draft a problem statement, propose architecture with technical specifics, document risks with mitigations').

DimensionReasoningScore

Specificity

The description names the domain ('architectural proposals') and one concrete action ('write comprehensive architectural proposals that drive alignment before code is written'), but does not list multiple specific concrete actions, matching anchor 3 rather than the multi-action anchor 5.

3 / 5

Completeness

It has a clear 'what' but no explicit 'Use when...' trigger clause; 'before code is written' is purpose rather than a triggering condition, so per the rubric's missing-trigger cap it stays at 3.

3 / 5

Trigger Term Quality

It includes relevant domain terms ('architectural proposals', 'alignment', 'before code is written') but lacks common variations, synonyms, or file/extension triggers, fitting anchor 3 rather than the comprehensive anchor 4-5.

3 / 5

Distinctiveness Conflict Risk

The niche is specific (pre-code architectural proposals driving alignment) and mostly distinct from other skills, with only minor overlap risk with general planning/design skills, matching anchor 4.

4 / 5

Total

13

/

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

github/gh-aw

Path

.squad/templates/skills/architectural-proposals/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.