CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Use inside coding-harness when the user wants to find architecture deepening opportunities, reduce shallow/pass-through modules, improve testability, or make the Codex-first harness easier for agents to navigate while staying aligned with docs/roadmap/north-star.md.

Quality

84%

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

SKILL.md
Quality
Evals
Security

Quality

Content

85%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 advisory skill body: lean and jargon-free of filler, with a clearly sequenced workflow containing explicit validation checkpoints and user gates, and exemplary progressive disclosure across four appropriately scoped reference files. The only notable improvements are minor de-duplication of reference links and slightly more concrete framing of the exploratory workflow steps.

DimensionReasoningScore

Conciseness

The body is lean: terse vocabulary rules, a numbered workflow, and a concrete output format, with no explanation of concepts Claude already knows. It is not a 5 because the References section re-lists links already given inline in Vocabulary/Workflow, and the Source Material provenance section could be folded into a single line.

4 / 5

Actionability

Gives concrete, executable guidance: exact doc paths ('docs/roadmap/north-star.md'), a runnable command ('pnpm skill:validate'), specific heuristics ('Apply the deletion test', 'Flag seams with only one adapter'), and a 7-field candidate output template. Not a 5 because some direction remains interpretive ('explore from throughput pressure', 'grill the design') without a worked example.

4 / 5

Workflow Clarity

The 5-step workflow is clearly sequenced with explicit preconditions ('Read the contract first'), a validation checkpoint for findings ('run or inspect the smallest relevant path ... before calling a module shallow'), a checklist for candidate output, an ask-the-user gate before implementation, and a documented validation command. As an advisory, non-destructive skill, no validation cap applies.

5 / 5

Progressive Disclosure

The body is an overview that appropriately splits detail into four real one-level-deep bundle files, each linked with a clear when-to-use signal (vocabulary in language.md, dependency classification in deepening.md, interface shapes in interface-design.md, context updates in context-and-decisions.md), plus a Table of Contents for navigation.

5 / 5

Total

18

/

20

Passed

Description

78%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 strong, well-scoped description with an explicit 'Use when' trigger clause, several concrete action phrases, and tight project-specific distinctiveness. Its main weakness is that the capability statement is bundled into trigger phrasing and uses project jargon, leaving minor gaps in what-output and synonym coverage.

DimensionReasoningScore

Specificity

The description lists several concrete actions — 'find architecture deepening opportunities', 'reduce shallow/pass-through modules', 'improve testability', 'make the Codex-first harness easier for agents to navigate' — with only minor coverage gaps. It falls short of 5 because the actions rely on project jargon rather than fully concrete capability statements, and the skill's actual output (a ranked candidate list) is not stated.

4 / 5

Completeness

An explicit trigger clause is present ('Use inside coding-harness when the user wants to...'), so no cap applies, and the 'what' is conveyed through the listed actions. Not a 5 because the 'what' is folded into the trigger actions rather than explicitly stated as what the skill does (e.g., returns ranked deepening candidates).

4 / 5

Trigger Term Quality

Includes natural trigger phrases users would say: 'improve testability', 'reduce shallow/pass-through modules', 'easier for agents to navigate'. Good keyword coverage, but misses common synonyms a user might naturally say such as 'refactor', 'reduce coupling', or 'code structure', so it is not a 5.

4 / 5

Distinctiveness Conflict Risk

Scopes itself tightly with 'inside coding-harness', 'Codex-first harness', and alignment with 'docs/roadmap/north-star.md' — a clear niche with distinct triggers and minimal conflict risk with other skills.

5 / 5

Total

17

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

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

Warning

relative_links

Relative link issues: 2 suspicious

Warning

Total

14

/

16

Passed

Repository

jscraik/coding-harness

Path

.agents/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.