CtrlK
BlogDocsLog inGet started
Tessl Logo

create-architecture

Author the architecture blueprint before code is written. Validates decisions against the pinned engine, flags knowledge gaps.

57

Quality

72%

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 ./.claude/skills/create-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

This is a dense, well-sequenced orchestration skill: every phase carries exact commands, verbatim prompts, templates, and approval/validation checkpoints, with explicit feedback loops on REJECT/INFEASIBLE verdicts. Its weaknesses are repetition — the approval-and-record boilerplate recurs across phases and update-mode rules are stated twice — and a preface that sits before the main heading.

Suggestions

Factor the per-phase pattern ("Get user approval on X, then record it in `production/session-state/active.md`; it is written at Phase 7") into one rule in the Collaborative Protocol instead of repeating it in Phases 1-4.

State the update/focus-area write behavior once (Phase 0e) and have Phase 7 reference it rather than restate it.

Move the preface (config-resolution note, docs.density and workflow tables) below the `# Create Architecture` heading so the document opens with its purpose.

DimensionReasoningScore

Conciseness

There is no padding and no explanation of concepts Claude already knows — the prose is almost entirely directives, tables, and templates. But the per-phase boilerplate ("Get user approval on X, then record it in `production/session-state/active.md`; it is written at Phase 7") repeats near-verbatim in Phases 1-4, and the update/focus-area write rules are stated twice (Phase 0e and again in Phase 7), so noticeable tightening is possible. Not anchor 4: these are more than minor trim instances; not anchor 2: the verbosity is repetition of genuinely needed rules, not unnecessary explanation.

3 / 5

Actionability

Fully executable throughout: exact grep invocations with pattern/glob/-A flags, verbatim AskUserQuestion prompts with labeled [A]/[B]/[C] options, exact output templates (Technical Requirements Baseline table, handoff block, sign-off status lines, the full document structure), and specific file paths for every artifact. This matches the anchor-5 "copy-paste ready, covers the common cases" bar.

5 / 5

Workflow Clarity

Phases 0-8 are explicitly sequenced with numbered sub-steps, an approval checkpoint before every write, and explicit feedback loops — "If either verdict is REJECT or INFEASIBLE, do not offer `Accept`", "Revise flagged items first" re-drafts and re-approves, plus a closing Gate-Check Readiness checklist. Anchors below 5 all describe missing or implicit checkpoints, none of which apply.

5 / 5

Progressive Disclosure

All external references are one level deep and clearly signaled with exact paths ("`.claude/docs/director-gates/[gate-id].md`", ".claude/docs/workflow-modes.md", engine-reference module docs), and the body even specifies that the spawned agent reads its own gate file rather than the parent. Minor gaps keep it from anchor 5: the config/density/workflow preface sits above the `# Create Architecture` H1, the full handoff template is inlined rather than referenced, and the ~585-line body carries several sections (e.g. the argument-mode table) that a reference file could absorb. Not anchor 3: references are clearly signaled and the inline content is procedural orchestration, not reference material that clearly belongs in separate files.

4 / 5

Total

17

/

20

Passed

Description

55%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 states three specific, concrete actions in third person, but omits any "Use when..." trigger guidance and leans on project jargon ("pinned engine", "knowledge gaps") rather than natural user phrases. It is functional yet below the bar set by the reference good examples, mainly on the completeness and trigger dimensions.

Suggestions

Add an explicit "when" clause, e.g. "Use when creating or updating the architecture blueprint before implementation or sprint planning begins, or when the user mentions architecture, layer design, data flow, or ADR gaps."

Swap project jargon for natural trigger terms: "pinned engine" → "the project's game engine/version", "flags knowledge gaps" → "identifies engine features the model may be out of date on".

State the distinction from sibling skills inline — e.g. "Creates the whole-system blueprint (distinct from /architecture-decision, which records individual ADRs)" — so an "architecture" query routes to the right skill.

DimensionReasoningScore

Specificity

Three concrete verb phrases — "Author the architecture blueprint before code is written", "Validates decisions against the pinned engine", "flags knowledge gaps" — parallel the anchor-4 example ("Extracts text from PDF files, fills forms, converts pages to images") in both count and concreteness. Not anchor 3, which covers only "1-2 concrete actions"; not anchor 5 because major scope (layer mapping, data flow, API boundaries, ADR audit) is left unmentioned, so coverage gaps are more than minor.

4 / 5

Completeness

The "what" is clear (author blueprint, validate decisions against the engine, flag knowledge gaps), but there is no "when" clause or equivalent explicit trigger guidance, which caps completeness at 3 per the rubric guideline. Not anchor 4 or 5, both of which require an explicit "Use when..." statement or concrete trigger phrases.

3 / 5

Trigger Term Quality

"architecture blueprint" is a plausible natural term, but the description is missing common variations and synonyms users would actually say ("design the architecture", "technical design", "architecture document"). Not anchor 4: "pinned engine" and "knowledge gaps" are project-internal jargon rather than natural user trigger phrases, so keyword coverage is only partial.

3 / 5

Distinctiveness Conflict Risk

The trigger word "architecture" is shared with sibling skills this body itself names ("/architecture-decision", "/architecture-review"), and the description states nothing that distinguishes this skill from them, so a user asking about "architecture" could route to the wrong skill. Not anchor 4: overlap with closely related same-family skills is more than minor; not anchor 2: "pinned engine" validation is too niche to conflict broadly.

3 / 5

Total

13

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (595 lines); consider splitting into references/ and linking

Warning

allowed_tools_field

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

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

13

/

16

Passed

Repository
Donchitos/Claude-Code-Game-Studios
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.