CtrlK
BlogDocsLog inGet started
Tessl Logo

architecture-survey

Periodic architecture survey — walks the module graph and reports ranked deepening candidates (shallow modules, hypothetical seams, logic behind the wrong seam). Survey, not rescue: it finds candidates and hands them to the captain; it never refactors on its own.

56

Quality

65%

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

Quality

Content

71%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 well-structured, genuinely actionable instruction-only skill: the survey procedure, finding heuristics, demolition test, and report contract are all concrete enough to execute, and the section organization is clean with an explicit completion definition. Its main cost is sustained nautical metaphor that decorates nearly every section without adding instruction, and the absence of a single worked example keeps the report format one step short of fully unambiguous.

Suggestions

Cut or reduce the decorative metaphor ("charts the reef", "the yard's busy water", "reads one card, not the whole reef", "simply sinks") — it appears in almost every section and adds tokens without adding instruction.

Add one short worked example of a candidate card (evidence file:line, deepening move, risk note, severity/confidence/actionable labels) so the report contract is unambiguous on first use.

State the commit-history weighting step in plain operational terms ("read recent commit history and focus on the most-edited areas") rather than as an extended metaphor.

DimensionReasoningScore

Conciseness

The instructional content itself is lean and assumes competence — finding definitions, the demolition test, and report structure are all stated without padding — but decorative nautical metaphor is sprinkled throughout ("A surveyor charts the reef; the captain decides whether to dredge", "weight the walk toward the yard's busy water", "the captain reads one card, not the whole reef", "it simply sinks"), and each instance costs tokens without adding instruction. Not a 2 because no section explains concepts Claude already knows and the body is short; not a 4 because the metaphorical padding recurs in nearly every section and could be cut.

3 / 5

Actionability

The guidance is concretely executable for an instruction-only skill: a three-step procedure, mechanically checkable heuristics ("a boundary crossed by exactly one adapter with no second caller; checkable by counting callers"), a falsifiable demolition test applied to every suspect, and a fully specified report format (evidence at file:line, one-sentence deepening move, risk note, top recommendation). Not a 5 because there is no worked example of a finding or a sample candidate card, which would make the report contract unambiguous.

4 / 5

Workflow Clarity

The sequence is clear and ordered: read principles and seam vocabulary → walk the module graph (with an explicit weighting rule via commit history) → classify findings → apply the demolition test filter → rank by leverage against risk → report → handoff. The demolition test acts as a per-suspect checkpoint and the completion definition ("report exists with evidence, rankings, and risk notes — and no file was modified") is an explicit end-state check. Not a 5 because there are no feedback loops or mid-survey error-recovery steps, though the skill is non-destructive so the validation cap does not apply.

4 / 5

Progressive Disclosure

This is a compact single-purpose skill (~50 lines) with no bundle files (no references/, scripts/, or assets/ exist), and the body is organized into six well-labeled sections (When to survey, The survey, The report, Handoff, Non-goals, Completion definition) that are easy to navigate. The only file paths mentioned (CLAUDE.md, ADRs, docs/standards/architecture.md) are artifacts of the repo being surveyed, not skill-bundle references, so no nesting or splitting is needed.

5 / 5

Total

16

/

20

Passed

Description

58%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 specific, well-bounded description that clearly states what the skill does and what it will not do, but it buries its triggers in internal jargon and nautical metaphor rather than natural user phrasing, and it lacks any explicit "Use when..." guidance. The what is strong; the when is barely implied.

Suggestions

Add an explicit trigger clause, e.g. "Use when the repo feels harder to change, before planning a refactoring effort, or periodically during active building" — the single word "Periodic" is too weak to carry the when.

Replace metaphorical phrasing ("hands them to the captain", "Survey, not rescue") with plain capability statements ("reports candidates for the maintainer to decide on; makes no edits").

Include natural synonyms users would actually say — "refactoring candidates", "shallow modules", "code health" — so the skill triggers on real requests rather than internal vocabulary.

DimensionReasoningScore

Specificity

The description lists several concrete actions — "walks the module graph", "reports ranked deepening candidates" — and enumerates the three finding classes ("shallow modules, hypothetical seams, logic behind the wrong seam") plus an explicit boundary ("it never refactors on its own"). It stops short of a 5 because the actions are stated in domain jargon rather than operational terms, leaving minor gaps in what the survey actually produces.

4 / 5

Completeness

The "what" is clear (walk the module graph, report ranked deepening candidates), but the "when" is only weakly implied by the single word "Periodic" — there is no "Use when..." clause or equivalent explicit trigger guidance, which the guidelines say caps completeness at 3. Not a 2 because the "what" half is specific and complete, not vague.

3 / 5

Trigger Term Quality

"Periodic architecture survey" and "module graph" are relevant keywords a user might plausibly say, but natural variations users would actually utter ("refactoring candidates", "code health", "technical debt", "deep modules") are absent, and the metaphorical framing ("hands them to the captain", "rescue") works against natural trigger phrasing. Not a 4: coverage is thin and no synonyms or explicit user-facing trigger phrases appear.

3 / 5

Distinctiveness Conflict Risk

The niche is fairly distinct — an architecture survey with named finding classes and an explicit "never refactors" boundary separates it from refactoring and code-review skills. Minor overlap risk remains with general code-review or audit skills since "architecture survey" alone doesn't fully disambiguate; not a 5 because the finding-class jargon, while distinctive, is internal vocabulary rather than a clearly staked trigger territory.

4 / 5

Total

14

/

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
Yeachan-Heo/oh-my-claudecode
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.