CtrlK
BlogDocsLog inGet started
Tessl Logo

architectural-proposals

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

58

Quality

67%

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 ./.copilot/skills/architectural-proposals/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

85%

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 templates, worked examples, and explicit review checkpoints; the only weakness is mild redundancy where the Examples section recaps the Patterns section.

DimensionReasoningScore

Conciseness

The body is dense and assumes Claude's competence (no basic-concept padding), but the 10-item 'Key patterns demonstrated' list largely restates the Patterns section and the wave example repeats, so it could be tightened.

2 / 3

Actionability

Concrete section templates, a worked decision-framing code block, a risk example with a specific '1000-message stream' test, named libraries (ink/blessed/readline), and exact file paths make the guidance copy-paste ready, matching the fully-executable anchor.

3 / 3

Workflow Clarity

Processes are clearly sequenced (7 required sections, 4-step wave restructuring, 10-step example) with the 'Needs sign-off from' checkpoint and the Always/Never + red-flags review lists acting as explicit validation gates.

3 / 3

Progressive Disclosure

No bundle files exist; the skill is self-contained with clear headers and logical sections enabling easy navigation, and there are no nested multi-level references, matching the well-organized self-contained anchor.

3 / 3

Total

11

/

12

Passed

Description

50%

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 conveys a clear purpose and distinct niche but relies on a single broad action verb and omits any explicit 'Use when...' trigger guidance, leaving every dimension at the mid-level anchor.

Suggestions

Add an explicit 'Use when...' trigger clause enumerating natural conditions, e.g. 'Use when architecture shifts invalidate assumptions, product direction changes require a new foundation, multi-wave decisions are needed, or external dependencies change.'

Replace the single broad verb 'write ... proposals' with several specific concrete actions (e.g. 'Draft problem statements with measurable evidence, propose architectures with technical specifics, restructure waves, frame decisions with sign-off, document risks with mitigations').

Add natural trigger-term variations users would actually say ('architecture proposal', 'design doc', 'RFC', 'technical proposal', 'alignment before building') to broaden trigger coverage.

DimensionReasoningScore

Specificity

The description names the domain ('architectural proposals') and one broad action/outcome ('drive alignment before code is written') but does not list multiple specific concrete actions, matching the 'names domain and some actions, but not comprehensive' anchor.

2 / 3

Completeness

It clearly states what the skill does, but lacks an explicit 'Use when...' trigger clause; 'before code is written' describes action timing rather than trigger conditions, capping completeness at 2 per the guidelines.

2 / 3

Trigger Term Quality

'architectural proposals' and 'alignment' are terms a user might say, but coverage is thin with no common variations, matching 'some relevant keywords but missing common variations' rather than the full-coverage anchor 3.

2 / 3

Distinctiveness Conflict Risk

It names a fairly distinct niche but the weak trigger surface means it could still overlap with general planning or design-doc skills, matching 'somewhat specific but could still overlap' rather than the clear-niche anchor 3.

2 / 3

Total

8

/

12

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.

Validation15 / 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
bradygaster/squad
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.