CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

55

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.grok/skills/improve-codebase-architecture/SKILL.md

The canonical home for this skill is improve-codebase-architecture in mattpocock/skills

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.

The body is a tightly written, highly actionable process skill with a clear phased workflow and explicit user-interaction checkpoints. Its main structural weakness is that its single outward reference, HTML-REPORT.md, is not present in the bundle, breaking the progressive-disclosure path for the HTML scaffold.

Suggestions

Add the missing HTML-REPORT.md bundle file (or move it into references/ and fix the link) so the delegated scaffold, diagram patterns, and styling guidance actually resolve.

Include one brief worked example of a candidate card (problem → solution → before/after sketch) so the report format is unambiguous without opening the external file.

Add a fallback step for the degenerate cases: no friction found, or the user's chosen candidate fails the grilling — currently the workflow has no guidance for either.

DimensionReasoningScore

Conciseness

The body is dense and instructional with almost no padding — it never explains concepts Claude already knows (what git log is, what Tailwind is) and confines itself to decisions and constraints specific to this workflow. Minor trimmable spots exist (e.g., "so nothing lands in the repo", the rationale in "Deepening a module pays off by making future changes to it easier"), placing it at anchor 4 (efficient, minor over-explanation) rather than anchor 5's every-token-earns-its-place, and far above anchors 1–2's padded exposition.

4 / 5

Actionability

Concrete, executable specifics abound: `git log --oneline` for hot spots, resolving the temp dir from `$TMPDIR` with a `/tmp` fallback, the exact file pattern `<tmpdir>/architecture-review-<timestamp>.html`, per-OS open commands (`xdg-open`, `open`, `start`), an enumerated card schema, and named recommendation-strength values. It is an instruction-only skill, so absent code is not penalized; the gaps that hold it at anchor 4 rather than 5 are the delegated HTML scaffold (in a separate file) and the absence of any concrete example of a candidate or grilling question.

4 / 5

Workflow Clarity

A clear three-phase sequence (Explore → Present → Grilling) with explicit checkpoints: scope decision logic before scanning, "Do NOT propose interfaces yet. After the file is written, ask the user", ADR-conflict gating ("only surface it when the friction is real enough"), and conditions for offering an ADR. It sits at anchor 4 (clear sequence, most checkpoints, minor gaps) rather than 5 because some checks are phrased as judgment calls without feedback loops — e.g., no instruction for what to do if no candidates are found or the user's pick turns out infeasible — and above anchor 3, whose defining trait (absent/implicit checkpoints) does not apply given the explicit stop-and-ask gate.

4 / 5

Progressive Disclosure

The body itself is well structured (short overview, vocabulary section, three phase sections), and the HTML scaffold is appropriately split out behind a clearly signaled one-level reference — "See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance". However, HTML-REPORT.md does not exist in the bundle (no references/ directory and no such file anywhere), so the primary detailed reference is broken and the navigation it promises cannot be followed. That lands between anchor 3 (structure present but organization compromised) and anchor 4 (good structure, references mostly clear); a missing referenced file is more than a "minor organization gap", so 3 is the better fit.

3 / 5

Total

15

/

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 communicates a distinctive three-step capability but relies on the skill's internal vocabulary ("deepening opportunities", "grill") instead of terms a user would actually say, and it entirely omits when to use it. It reads as a mid-tier description: clear shape, weak triggering.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user wants to improve codebase architecture, reduce coupling, or plan a refactoring."

Replace internal jargon with user-facing language: "deepening opportunities" → "refactoring opportunities that simplify interfaces"; "grill through" → "walk through the trade-offs".

Include natural synonyms such as "architecture review", "refactor", "module design", "technical debt" so the skill triggers on phrasings users actually produce.

DimensionReasoningScore

Specificity

The description names the domain ("a codebase") and three action steps ("Scan ... for deepening opportunities", "present them as a visual HTML report", "then grill through whichever one you pick"), but the core capability hinges on opaque internal jargon — "deepening opportunities" and "grill" never state what concretely happens (e.g., refactoring shallow modules, discussing constraints). It matches anchor 3 (domain plus 1–2 concrete actions, not comprehensive) more than anchor 4, which expects several clearly specific actions: the first and most important action is the least concrete.

3 / 5

Completeness

The "what" is stated clearly (scan, present a report, walk through one pick), but there is no "Use when..." clause or equivalent trigger guidance anywhere in the description — per the judging guidelines this caps completeness at 3, which is also the exact anchor (clear 'what', 'when' missing). It cannot be a 4 without any explicit 'when', and is above a 2 because the 'what' is substantive rather than vague.

3 / 5

Trigger Term Quality

Some natural keywords are present ("codebase", "scan", "HTML report"), but common user phrasings for this need are missing: "architecture", "refactor", "review", "improve the design", "technical debt". "Grill" is the author's own vocabulary, not something a user would say when they need this skill. Anchor 3 (some relevant keywords, missing common variations or synonyms) fits; it is above anchor 2 because more than generic language is present, but well below anchor 5's synonym/extension coverage.

3 / 5

Distinctiveness Conflict Risk

The niche — architecture-deepening scan delivered as a visual HTML report followed by an interactive walkthrough — is fairly distinct, with only minor overlap risk against generic code-review or refactoring skills. It fits anchor 4 (mostly distinct, minor overlap with closely related skills): more distinguishable than anchor 3's "Works with document files"-level overlap, but not a fully isolated niche since "scan a codebase" could collide with review/analysis skills absent trigger phrases.

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

relative_links

Relative link issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

saif-shines/doraval

Path

.grok/skills/improve-codebase-architecture/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.