best-practices

Transforms vague prompts into optimized Claude Code prompts. Adds verification, specific context, constraints, and proper phasing. Invoke with /best-practices.

Quality

63%

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/best-practices/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.

This is a well-structured instruction skill with genuinely actionable tables, examples, and a clear routing workflow, supported by a real one-level-deep reference bundle. Its main costs are redundancy — repeated examples and two overlapping self-evaluation rubrics — and a broken dependency on an absent agents/ directory for the "Build context first" branch. Tightening the duplicates and fixing or removing the agent references would move it into the top band on both conciseness and progressive disclosure.

Suggestions

Delete the Quick Transformation Examples section (or reduce it to 2-3 cases) and point to references/before-after-examples.md, which already contains the 50+ examples; likewise merge the duplicated "fix the API error" and "fix the login bug" examples.

Merge "Quick Prompt Quality Check" and "Success Criteria — Prompt Quality Eval" into a single rubric section, since both score the same five principles.

Fix the "Build context first" branch: either ship the three agent definition files in agents/ or replace the Task-tool snippet with inline instructions Claude can execute directly.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient (tables and before/after blocks rather than padded prose), but it contains clear duplication: the "fix the API error" example appears in both Principle 1 and the "With Verification Report" section, "fix the login bug" appears in Principle 2 and again in Quick Transformation Examples, and the "Quick Prompt Quality Check" and "Success Criteria" sections restate the same rubric twice. This fits the 'mostly efficient but could be tightened' anchor rather than the minor-trim anchor 4.	3 / 5
Actionability	Guidance is largely executable for an instruction skill: concrete vague→specific mapping tables, copy-paste before/after examples, an explicit output format template, a fallback question, and a pre-output checklist. The gap keeping it from 5 is the agent-invocation snippet referencing agents (agents/task-intent-analyzer.md etc.) whose definitions are not present in the bundle, making that branch semi-pseudocode.	4 / 5
Workflow Clarity	The flow is clearly sequenced (Start Here routing → mode selection → 4-step transformation workflow → checklist → fallback), with the Transformation Checklist acting as a pre-output validation checkpoint. It is not a destructive or batch operation so no cap applies, but the "Build context first" branch's post-agent steps lack the error-recovery feedback loops of the anchor 5 example.	4 / 5
Progressive Disclosure	Structure is good: the Reference Files section clearly signals five one-level-deep references (all verified to exist in references/), and the overview vs. detail split is mostly appropriate. It falls short of anchor 5 because ~120 lines of Quick Transformation Examples duplicate material that belongs in the already-referenced before-after-examples.md ("50+ Examples"), and the body references an agents/ directory that does not exist in the bundle.	4 / 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 communicates what the skill does with concrete, third-person actions, but it lacks any "Use when..." trigger guidance, so Claude has little basis to invoke it automatically. Natural trigger phrasing users would actually say is also missing. Adding an explicit when-to-use clause with common trigger phrases would lift the two heaviest-weighted dimensions.

Suggestions

Append an explicit trigger clause, e.g. "Use when the user asks to improve, optimize, rewrite, or evaluate a prompt, or mentions prompt engineering or best practices."

Add natural synonyms users would say ("improve my prompt", "make this prompt better", "prompt engineering") to broaden trigger-term coverage.

Optionally enumerate the transformation dimensions as noun phrases users might echo (verification, context, constraints, phasing, rich content) instead of compressing them into one sentence.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions in third person ("Transforms vague prompts", "Adds verification, specific context, constraints, and proper phasing") with only minor coverage gaps, matching the 'several specific actions' anchor rather than the fully comprehensive anchor 5.	4 / 5
Completeness	The "what" is clear (transforms vague prompts by adding verification, context, constraints, phasing) but the "when" is entirely missing — "Invoke with /best-practices" tells how to invoke, not when the skill should trigger, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	It includes some relevant keywords ("prompts", "vague prompts", "verification") but misses natural phrases users would actually say such as "improve my prompt", "rewrite this prompt", or "prompt engineering"; "Invoke with /best-practices" is invocation mechanics rather than a trigger term.	3 / 5
Distinctiveness Conflict Risk	"Transforms vague prompts into optimized Claude Code prompts" carves a clear niche that is mostly distinct from other skills, with only minor overlap risk against generic prompt-engineering helpers.	4 / 5
	Total	14 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (502 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: MoizIbnYousaf/ai-agent-skills
Path: skills/best-practices/SKILL.md
Commit: 6d95c78

Reviewed: 6 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.