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, build, or author a new skill.

63

Quality

79%

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

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.

A strong, actionable authoring guide with a copy-paste template, concrete thresholds, and a programmatic validation path. Its main gaps are navigational and structural: most bundle reference files are unreachable from the body, and the body violates its own 100-line splitting rule.

Suggestions

Link the remaining reference files (description_design_patterns.md, progressive_disclosure_principles.md, quality_gates_for_skills.md) from the body — e.g., in a 'Further reading' or relevant section — so they are discoverable rather than orphaned in references/.

Trim the body under 100 lines to honor its own split rule, moving the detailed Description Requirements guidance into references/description_design_patterns.md and keeping only the essential rules inline.

Wire the checklist/runner into the 3-phase process as an explicit validate → fix → re-run loop (e.g., "Run the runner; if any item fails, fix and re-run until PASS") to complete the workflow's feedback loop.

DimensionReasoningScore

Conciseness

The body is lean and imperative — process, structure diagram, template, thresholds, and checklists with no explanations of concepts Claude already knows. Minor trimmable padding remains (e.g., the rationale line after the bad description example, the version footer), so it sits at anchor 4 rather than 5.

4 / 5

Actionability

Concrete, copy-paste-ready guidance throughout: a complete SKILL.md template with frontmatter, explicit split thresholds ("exceeds 100 lines", "exceeds 500 lines"), good/bad description examples, and the runnable command "python scripts/skill_review_checklist_runner.py path/to/skill-folder". Falls short of anchor 5 because there is no complete worked example of a finished skill.

4 / 5

Workflow Clarity

The 3-phase process (Gather requirements → Draft → Review with user) is a clear sequence, and the "Review Checklist — After drafting, verify" section plus the programmatic runner provide explicit validation checkpoints. Not anchor 5 because the sequence lacks an explicit fix-and-revalidate loop or gating ("only proceed when validation passes") — what to do when the checklist fails is left implicit.

4 / 5

Progressive Disclosure

Sections are clearly organized and the referenced file (references/companion_tooling.md) is real and one level deep, but 3 of the 4 files in references/ (description_design_patterns.md, progressive_disclosure_principles.md, quality_gates_for_skills.md) are never signposted from the body, and the ~145-line body exceeds the skill's own 100-line split rule with inline content (detailed description-authoring guidance) its own criteria would move to a reference file. This matches anchor 3 — structure present, but references not fully signaled and content that should be separate is inline.

3 / 5

Total

15

/

20

Passed

Description

78%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 well-formed description that explicitly answers both what and when with a concrete multi-verb trigger clause. Its main weakness is the 'what' half, which states a single action plus output qualities rather than enumerating the concrete authoring actions the skill performs.

Suggestions

Enumerate 2-3 more concrete actions in the first sentence (e.g., "Draft SKILL.md files with descriptions, structure, and bundled scripts; review against a quality checklist") so specificity reaches the comprehensive level.

Add natural noun-phrase triggers such as "SKILL.md" or "skill authoring" to widen keyword coverage beyond the single word "skill".

DimensionReasoningScore

Specificity

"Create new agent skills" names the domain and one concrete action, but "with proper structure, progressive disclosure, and bundled resources" lists output qualities rather than additional actions (drafting, reviewing, validating), so coverage is not comprehensive. It matches anchor 3 (domain + 1-2 concrete actions); not 4 because the remainder of the sentence describes attributes rather than several specific actions.

3 / 5

Completeness

Both parts are explicit: what — "Create new agent skills with proper structure, progressive disclosure, and bundled resources"; when — "Use when user wants to create, write, build, or author a new skill" with concrete trigger verbs. The 'when' clause is more specific than anchor 4's example ("Use when working with PDF files"), so it fits anchor 5.

5 / 5

Trigger Term Quality

"Use when user wants to create, write, build, or author a new skill" gives good natural-verb coverage (create/write/build/author are phrases users would actually say). Not 5 because the noun space is only "skill" — no synonyms or artifacts like "SKILL.md", "skill authoring", or "slash command".

4 / 5

Distinctiveness Conflict Risk

Skill authoring is a clear niche with distinct triggers, so it is mostly distinguishable from unrelated skills. Minor overlap risk remains with closely related companion skills (e.g., document-to-skill compilation), which the description does not disambiguate — fits anchor 4 rather than 5.

4 / 5

Total

16

/

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

alirezarezvani/claude-skills

Path

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