improve-codebase-architecture

扫描代码库中的深化机会，生成可视化 HTML 报告，然后围绕你选中的候选项继续追问。

Quality

65%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

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 content is a well-structured, actionable instruction-only skill with a clear sequenced workflow and concrete commands; its main weakness is that the single referenced detail file (HTML-REPORT.md) does not exist in the bundle.

Suggestions

Provide the referenced HTML-REPORT.md (or inline the HTML scaffold/diagram patterns it promises) so the [HTML-REPORT.md](HTML-REPORT.md) link is not broken.

If HTML-REPORT.md is intentionally omitted, remove or replace the reference with inline minimal scaffolding so navigation does not dead-end.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and assumes Claude's competence — it explains project-specific vocabulary (deletion test, seams, ADRs) rather than generic CS concepts — with only minor spots that could be trimmed.	4 / 5
Actionability	Concrete guidance is strong: explicit temp-dir resolution ($TMPDIR//tmp/%TEMP%), file path pattern, per-OS open commands (xdg-open/open/start), Tailwind/Mermaid via CDN, and enumerated card fields, with the main gap being the HTML scaffold deferred to the missing HTML-REPORT.md.	4 / 5
Workflow Clarity	A clear 3-step sequence (Explore → HTML report → Grilling loop) with an explicit user checkpoint ('写完文件后问用户') and defined grilling sub-steps; minor gap is the lack of any validation of the generated report.	4 / 5
Progressive Disclosure	The body is well-sectioned and points to a clearly-signaled one-level reference ([HTML-REPORT.md](HTML-REPORT.md)), but that referenced file is not present in the bundle, leaving a broken navigation link.	3 / 5
	Total	15 / 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.

The description clearly states three concrete actions and occupies a distinct niche, but it omits any explicit 'when to use' trigger guidance and leans on the project-specific term '深化机会' rather than natural user phrasing.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when reviewing codebase architecture for refactor opportunities or when the user asks how to deepen shallow modules.'

Add natural trigger synonyms users would actually say (e.g. 'architecture review', 'refactor opportunities', 'shallow modules') alongside '深化机会'.

Reconsider voice/phrasing so the trigger reads as something a user would naturally request rather than a description of internal mechanics.

Dimension	Reasoning	Score
Specificity	Three concrete actions are named — '扫描代码库中的深化机会', '生成可视化 HTML 报告', '继续追问' — comparable to the anchor listing several specific actions with minor coverage gaps.	4 / 5
Completeness	The 'what' is clear (scan, generate report, probe), but there is no 'Use when...' clause or equivalent explicit trigger guidance, so completeness is capped at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Relevant keywords like '代码库', 'HTML 报告', '候选项' appear, but the core trigger '深化机会' is project jargon from /codebase-design and common synonyms like 'architecture review' or 'refactor' are absent.	3 / 5
Distinctiveness Conflict Risk	The combination of architecture-deepening scan plus HTML report plus follow-up grilling is a distinct niche with only minor overlap risk against generic code-review skills.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: vinvcn/mattpocock-skills-zh-CN
Path: skills/engineering/improve-codebase-architecture/SKILL.md
Commit: 9fb0161

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.