CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

improve-codebase-architecture

Review code architecture, code quality, dependency graphs, coupling, technical debt, modularization, ownership, and test seams. Use when refactors, restructuring, tightly coupled code, or architecture decisions need proof-backed options.

Quality

80%

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/agent-ops/improve-codebase-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

67%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, strongly action-oriented skill body with a clear sequenced workflow, explicit validation gates and recovery loops, and sound progressive disclosure into real, verified reference files. The weakest point is token efficiency: a large environment-specific validation command block and dense noun-string phrasing pad the file without adding runtime guidance.

Suggestions

Move the 14 hard-coded validation commands into a referenced CI/checklist file (or scripts/), keeping only the gate order and "stop at first failed gate" rule in SKILL.md — this addresses the lowest-scoring dimension (conciseness).

Add one inline compact example of a structured output instance (or a pointer early in Outputs to a concrete filled-in example in references/output-schema.md) so the workflow's final artifact is executable without interpretation.

Either mention or prune the un-referenced bundle files (examples.md, scenario-review.md, discovery-interview.md, knowledge-capsule-routing.md, scorer-calibration/) so every shipped reference is reachable from the SKILL.md navigation surface.

DimensionReasoningScore

Conciseness

The core workflow is lean and imperative ("Prefer the smallest evidence-backed architecture move"), but the ~25-line Validation section embeds 14 environment-specific commands with hardcoded paths ("Skills/agent-ops/improve-codebase-architecture", "--tessl-workspace jscraik") that are CI/maintenance boilerplate rather than runtime guidance, and Inputs/Warehouse-style noun-string lists ("owner signal, public interface, callers, tests, generated/projection paths...") could be tightened. Not a 2 because no space is spent explaining concepts Claude already knows; not a 4 because the validation block and dense nominal phrasing add a real, noticeable token cost.

3 / 5

Actionability

Concrete guidance is present: a specific example target ("Infrastructure/scripts/lifecycle-and-sync/command_surface.py"), precise decision rules ("Prefer the reversible patch unless the current interface is the named liability and owner alignment, caller map, migration proof, rollback, and a tracer... exist"), and a full block of exact, executable validation commands. Not a 5 because the workflow steps themselves are conceptual imperatives with no worked example of a rendered output (the schema lives entirely in references/output-schema.md), and some steps require interpretation to execute.

4 / 5

Workflow Clarity

The numbered 10-step workflow has an explicit feedback loop and validation checkpoints: "Stop at the first failed gate; do not proceed until the blocker is classified... rerun the same gate before widening", plus step 10's post-validation re-review. Not a 5 because the per-step checkpoints are mostly embedded in prose rather than explicit commands or checklists (e.g., steps 2-6 give no concrete command for the preflight or caller mapping), which is the gap between this and the anchor-5 pattern of explicit validate/fix/retry at each step.

4 / 5

Progressive Disclosure

The body is a genuine overview with well-signaled one-level-deep references ("Use references/deepening-workflow.md for repository search patterns", "Classify with references/classification-cheatsheet.md"), and every cited file exists with real content; the References section cleanly separates core files, package policy, and evidence assets, with the capsule files delegated to knowledge-capsule.manifest.yaml. Not a 5 because several bundle files present on disk (examples.md, scenario-review.md, discovery-interview.md, knowledge-capsule-routing.md, scorer-calibration/) are never mentioned in the body, leaving minor navigation gaps into the wider bundle.

4 / 5

Total

15

/

20

Passed

Description

83%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 description that clearly and explicitly states both capabilities and use-when triggers with natural language a user would plausibly say. The main weakness is modest: one verb ("Review") covers everything, and "code quality" is a slightly generic term that overlaps with adjacent code-review skills.

DimensionReasoningScore

Specificity

"Review code architecture, code quality, dependency graphs, coupling, technical debt, modularization, ownership, and test seams" lists several specific review capabilities with concrete objects (dependency graphs, test seams, ownership), though a single verb ("Review") carries all of them, leaving minor gaps versus the comprehensive multi-action anchor. Not a 3 because coverage goes well beyond 1-2 actions; not a 5 because the action vocabulary is uniform (review-only) rather than multiple distinct concrete operations.

4 / 5

Completeness

Explicitly answers both questions: what ("Review code architecture, code quality, dependency graphs, coupling, technical debt, modularization, ownership, and test seams") and when ("Use when refactors, restructuring, tightly coupled code, or architecture decisions need proof-backed options") with concrete trigger phrases, matching the anchor-5 example structure.

5 / 5

Trigger Term Quality

Natural phrases a user would say appear directly: "refactors", "tightly coupled code", "architecture decisions", "coupling", "technical debt". Not a 5 because common variations like "design review", "clean up the codebase", or file/extension cues are absent; not a 3 because both domain nouns and colloquial trigger phrasings are present beyond a single generic keyword.

4 / 5

Distinctiveness Conflict Risk

Triggers like "coupling", "technical debt", "test seams", and "proof-backed options" carve a fairly distinct architecture-review niche, but "code quality" and "refactors" overlap with generic code-review and refactoring skills. Not a 3 — overlap is confined to closely related skills, not a broad conflict surface.

4 / 5

Total

17

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

jscraik/Agent-Skills

Path

Skills/agent-ops/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.