claude-md

Create or update CLAUDE.md files following best practices for optimal AI agent onboarding

Quality

60%

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 ./03-skills/claude-md/SKILL.md

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.

The body is well-structured and actionable with clear sequenced workflows and approval checkpoints, though it is slightly verbose due to overlapping constraint/anti-pattern/checklist sections and time-sensitive footer metadata.

Suggestions

Merge the Quality Constraints, Anti-Patterns to Avoid, and Validation Checklist into a single consolidated section to remove triple restatement of the same rules.

Move time-sensitive metadata (Last Updated, Claude Code Version, Compatible Models) out of the body or into a clearly marked version/deprecated section so it does not consume context tokens.

Consider extracting the full markdown template (Essential Sections) into a reference file so the body stays an overview, deepening the progressive-disclosure structure the skill itself advocates.

Dimension	Reasoning	Score
Conciseness	Largely efficient and declarative, but the Quality Constraints, Anti-Patterns, and Validation Checklist restate one another, and the footer carries time-sensitive info (Last Updated, Claude Code Version, Compatible Models) that the rubric penalizes outside a deprecated section — pulling it to 'mostly efficient with some unnecessary content'.	3 / 5
Actionability	As an instruction-only skill it provides concrete, specific guidance — exact file paths to check, a WHAT/WHY/HOW structure, a concrete agent_docs/ layout, a full markdown template, and the @AGENTS.md import mechanism — with only minor gaps (placeholder commands, no finished real-world example).	4 / 5
Workflow Clarity	Execution Flow and per-mode Output Formats are clearly numbered and gated by explicit approval checkpoints ('Present the draft for review', 'Write after approval', 'Apply changes after approval'), satisfying validation for the file-rewrite operations, but there is no explicit error-recovery feedback loop so it stays below 5.	4 / 5
Progressive Disclosure	Well-organized with clear section headers and it actively teaches progressive disclosure (agent_docs/ folder, file:line references), but the skill is a monolithic ~215-line file with no external references and inlines the large markdown template; good structure with minor organization gaps.	4 / 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 states a clear 'what' and is reasonably distinct, but it lacks an explicit 'when to use' trigger clause and undersells the skill's capabilities (omitting 'audit'), with only partial coverage of natural user trigger terms.

Suggestions

Add an explicit 'Use when...' trigger clause, e.g. 'Use when creating, updating, or auditing a CLAUDE.md, or when the user asks to set up project context for an AI agent.'

Include the 'audit' capability in the description so it reflects all three documented modes (create/update/audit).

Surface natural user phrases such as 'set up CLAUDE.md', 'write a CLAUDE.md', and 'agent instructions / project context file' to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('CLAUDE.md files') and two concrete actions ('Create or update') but omits the 'audit' capability documented in the body and pads with generic rationale ('following best practices for optimal AI agent onboarding'), matching the '1-2 concrete actions, not comprehensive' anchor.	3 / 5
Completeness	Has a clear 'what' (create/update CLAUDE.md) but no explicit 'Use when...' trigger clause; per the rubric a missing trigger clause caps completeness at 3, and the 'when' is only weakly implied via 'AI agent onboarding'.	3 / 5
Trigger Term Quality	Includes 'CLAUDE.md' and 'AI agent onboarding' but misses the natural phrases users actually say ('set up / write a CLAUDE.md', 'agent instructions', 'project context file'), so keyword coverage is partial rather than comprehensive.	3 / 5
Distinctiveness Conflict Risk	Tied to a specific named artifact (CLAUDE.md) with low overlap risk against other skills, though the broad 'best practices for AI agent onboarding' phrasing keeps it just below the fully-distinct anchor 5.	4 / 5
	Total	13 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: luongnv89/claude-howto
Path: 03-skills/claude-md/SKILL.md
Commit: 1c04dbf

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.