write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./engineering/write-a-skill/skills/write-a-skill/SKILL.md

Quality

Content

68%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-organized, concise meta-skill with a clear 3-phase workflow and genuine one-level-deep references to a companion tooling file. Its weakness is actionability: the authoring "steps" are user-interview prompts and a structural template rather than concrete executable guidance, and several bundled reference files are never surfaced from the body.

Suggestions

Make the authoring workflow executable: turn each Process phase into concrete actions (e.g. "run scripts/skill_description_validator.py --output json" after drafting the description) rather than only interview prompts.

Add explicit links to the unused bundled references (description_design_patterns.md, progressive_disclosure_principles.md, quality_gates_for_skills.md) from the relevant body sections so progressive disclosure is fully wired.

Trim the restated-basic explanations (the "Bad example" rationale, the "only thing your agent sees" preamble) that Claude already knows to lift conciseness toward a 5.

Dimension	Reasoning	Score
Conciseness	The body is largely efficient and assumes Claude's competence (e.g. terse template and bullet lists), but a few sections restate basics Claude already knows ("The description is the only thing your agent sees...", the "Bad example" walkthrough) that could be trimmed, keeping it just above the midpoint.	4 / 5
Actionability	It gives a concrete SKILL.md template and one runnable command (python scripts/skill_review_checklist_runner.py), but the core authoring steps are bullet prompts to "ask the user" rather than executable instructions, and the template is structural skeleton rather than copy-paste ready authored output.	3 / 5
Workflow Clarity	The 3-phase Process is clearly sequenced (Gather -> Draft -> Review) and the Review Checklist plus programmatic validation runner provide checkpoints, though the checklist itself is a static list rather than an explicit validate/fix/retry loop, leaving a minor validation gap.	4 / 5
Progressive Disclosure	The body is a concise overview with well-signaled one-level-deep references (references/companion_tooling.md and scripts/), and the bundle file exists, but the SKILL.md itself does not link to the other three reference files (description_design_patterns.md, progressive_disclosure_principles.md, quality_gates_for_skills.md) that sit alongside it, so discovery is incomplete.	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 with explicit what-and-when structure and natural trigger synonyms. The main weakness is specificity: the "actions" listed (structure, progressive disclosure, bundled resources) are attributes of a skill rather than concrete authoring operations, so it stays just below a fully comprehensive action list.

Suggestions

Replace the attribute list with concrete authoring verbs, e.g. "Create new agent skills: draft SKILL.md, split reference files, bundle utility scripts, and validate structure and descriptions."

Add at least one more natural trigger synonym such as "scaffold" or "set up a new skill" to broaden the trigger surface.

Consider naming the deliverable explicitly ("a SKILL.md with optional references/ and scripts/ bundles") to sharpen distinctiveness from generic authoring skills.

Dimension	Reasoning	Score
Specificity	"Create new agent skills with proper structure, progressive disclosure, and bundled resources" names the domain plus several concrete structural facets (structure, progressive disclosure, bundled resources), but the actions are themselves abstract processes rather than a list of concrete operations like extract/merge/fill, leaving minor coverage gaps.	4 / 5
Completeness	It clearly states what the skill does in the first sentence and provides an explicit "Use when ..." trigger clause with concrete verbs in the second, explicitly answering both what and when.	5 / 5
Trigger Term Quality	"Use when user wants to create, write, build, or author a new skill" offers good keyword coverage with natural synonyms (create/write/build/author), though it omits common variations like "define", "scaffold", or "skeleton a skill".	4 / 5
Distinctiveness Conflict Risk	"create, write, build, or author a new skill" carves a clear niche (skill authoring) with distinct triggers and minimal overlap risk against skills that merely use or consume skills.	5 / 5
	Total	18 / 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: alirezarezvani/claude-skills
Path: engineering/write-a-skill/skills/write-a-skill/SKILL.md
Commit: 19392f7

Reviewed: ~2 hours 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.