CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

write-a-skill

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

61

Quality

77%

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 ./.cursor/skills/write-a-skill/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

75%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 a tight, actionable guide for skill authoring with a concrete template, numeric thresholds, worked examples, and a review checklist, and it does not waste tokens teaching general concepts. Its weaknesses are minor: an ambiguity between the 500-line and 100-line split thresholds and a missing fix-and-retry loop after the review checklist.

Suggestions

Reconcile the file-size guidance: pick one threshold (e.g., split when SKILL.md exceeds 100 lines; move material out before it nears that) instead of the conflicting 500-line and 100-line figures.

Add a short error-recovery step after the Review Checklist (e.g., "If any box is unchecked, revise that section before presenting the draft again") to close the validate→fix→retry loop.

Trim the explanatory prose around the good/bad description examples — the examples carry the point on their own.

DimensionReasoningScore

Conciseness

The body is organized into short, purposeful sections (Process, Skill Structure, Template, Description Requirements, When to Add Scripts, When to Split Files, Review Checklist) with almost no padding. Minor over-explanation can be trimmed — e.g., "The bad example gives your agent no way to distinguish this from other document skills" restates what the adjacent example shows — so it fits 'efficient; minor instances of over-explanation' rather than the fully lean 5 anchor.

4 / 5

Actionability

Guidance is concrete and executable for an instruction-only skill: a copy-paste SKILL.md template, a directory tree, numeric thresholds ("Max 1024 chars", "SKILL.md exceeds 100 lines", "References one level deep"), and good/bad description examples. It falls short of the 5 anchor because of a minor internal inconsistency — "Additional reference files if content exceeds 500 lines" vs. "Split into separate files when SKILL.md exceeds 100 lines" — which leaves the split threshold ambiguous.

4 / 5

Workflow Clarity

The Process section gives a clear three-step sequence (gather requirements → draft → review with user), each with concrete sub-questions, and the Review Checklist provides a post-draft validation checkpoint. There is no error-recovery loop (what to do when a checklist item fails) and the workflow involves no destructive operations, so this sits at 4 rather than the explicit validate/fix/retry structure of a 5.

4 / 5

Progressive Disclosure

The single-file body is well organized with clearly headed sections, and it explicitly teaches one-level-deep reference structure in its own template and checklist; no bundle files exist to score against, and no references are buried. It is not a 5 because at ~117 lines some self-contained material (e.g., the full Description Requirements section with worked good/bad examples) is inlined where a real skill would split it out per its own 100-line guidance, and there are no actual external reference files demonstrating the pattern it prescribes.

4 / 5

Total

16

/

20

Passed

Description

70%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 is well-formed: third-person, under budget, with an explicit 'Use when' trigger clause covering natural verb synonyms. Its main weakness is the 'what' half, which states a single action decorated with feature attributes rather than enumerating several concrete capabilities.

Suggestions

Enumerate 2-3 concrete actions in the first sentence, e.g., "Creates new agent skills: drafts SKILL.md frontmatter and body, structures bundled reference files and scripts, and reviews drafts against a quality checklist."

Broaden trigger coverage with terms users actually type, such as "SKILL.md", "skill authoring", or "make Claude a new skill".

DimensionReasoningScore

Specificity

"Create new agent skills with proper structure, progressive disclosure, and bundled resources" names the domain (agent skills) and one concrete action (create), with the rest being attributes rather than actions. It does not list several distinct actions (e.g., create, validate, refactor, document), so it matches the 'domain plus 1-2 concrete actions' anchor rather than 'several specific actions'.

3 / 5

Completeness

It explicitly answers both: what ("Create new agent skills with proper structure, progressive disclosure, and bundled resources") and when ("Use when user wants to create, write, or build a new skill"). The 'when' clause is present and explicit but could be more specific about contexts or file types, matching the 4 anchor rather than the fully concrete trigger phrase coverage of a 5; it is clearly above the 3 anchor where 'when' is missing or only weakly implied.

4 / 5

Trigger Term Quality

"Use when user wants to create, write, or build a new skill" covers the natural verb variations users would say (create, write, build). A few natural terms are missing (e.g., "SKILL.md", "skill authoring", "slash command"), which fits the 'good keyword coverage; a few natural terms missing' anchor rather than the comprehensive synonym/extension coverage of a 5.

4 / 5

Distinctiveness Conflict Risk

"Create new agent skills" carves out a clear niche (skill authoring) with distinct triggers, giving minimal conflict with unrelated skills. It sits at 4 rather than 5 because there is minor overlap risk with closely related skills (e.g., editing or updating existing skills, or other authoring/documentation skills) that the trigger phrasing does not exclude.

4 / 5

Total

15

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

SnowingFox/ai-skills

Path

.cursor/skills/write-a-skill/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.