CtrlK
BlogDocsLog inGet started
Tessl Logo

writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

59

1.29x
Quality

37%

Does it follow best practices?

Impact

100%

1.29x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/writing-skills/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

40%

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 essentially just a 'Use when...' trigger clause without any explanation of what the skill actually does. It lacks specificity about concrete actions (e.g., generating SKILL.md files, validating frontmatter, testing skill selection) and doesn't adequately define the domain of 'skills' for disambiguation purposes.

Suggestions

Add a 'what it does' clause before the trigger, e.g., 'Generates, edits, and validates SKILL.md files including YAML frontmatter, description fields, and markdown content.'

Include more specific trigger terms users would naturally say, such as 'SKILL.md', 'skill file', 'skill template', 'frontmatter', 'write a new skill', or 'test skill matching'.

Clarify what 'verifying skills work before deployment' means concretely, e.g., 'validates skill syntax, tests description quality, and checks for frontmatter errors'.

DimensionReasoningScore

Specificity

The description uses vague language like 'creating', 'editing', and 'verifying' without specifying concrete actions. It doesn't explain what a 'skill' is, what creating one involves, or what verification entails.

1 / 3

Completeness

The description functions as a 'Use when...' clause addressing when to use the skill, but it lacks a clear 'what does this do' component explaining the concrete capabilities or outputs of the skill.

2 / 3

Trigger Term Quality

It includes some relevant keywords like 'skills', 'creating', 'editing', and 'deployment', but misses natural variations users might say such as 'SKILL.md', 'skill file', 'write a skill', 'test a skill', 'skill template', or 'frontmatter'.

2 / 3

Distinctiveness Conflict Risk

The term 'skills' provides some specificity to a niche domain, but 'creating', 'editing', and 'verifying' are generic enough that this could overlap with general file editing or testing skills. Without more detail about what skills are (e.g., markdown files, YAML frontmatter), the boundaries are unclear.

2 / 3

Total

7

/

12

Passed

Implementation

35%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a comprehensive but excessively verbose meta-skill about writing skills. Its greatest strength is the thorough coverage of CSO optimization, the concrete good/bad examples for YAML descriptions, and the structured checklist. Its greatest weakness is severe verbosity - it repeats core concepts (TDD mapping, Iron Law, no exceptions) multiple times, includes motivational content Claude doesn't need, and ironically violates its own token efficiency guidelines. The skill would benefit enormously from being cut to roughly 40% of its current length.

Suggestions

Cut the skill to under 500 words by removing repeated concepts (Iron Law appears 3+ times, TDD mapping is restated in multiple sections), the 8-row rationalization table, and motivational content Claude doesn't need.

Move the CSO section, bulletproofing/rationalization section, and testing-all-skill-types section to separate reference files, keeping only brief summaries with cross-references in the main SKILL.md.

Consolidate the workflow into a single clear sequence rather than scattering it across 'TDD Mapping', 'RED-GREEN-REFACTOR for Skills', 'The Iron Law', and 'Skill Creation Checklist' sections.

Add concrete validation criteria for the testing steps - what specific commands to run, what 'compliance' looks like, and how to determine when a skill is 'bulletproof' enough to deploy.

DimensionReasoningScore

Conciseness

This skill is extremely verbose at ~2500+ words. It explains concepts Claude already knows (what TDD is, what a skill is), repeats the same points multiple times (the Iron Law appears 3+ times, the TDD mapping is restated repeatedly), includes an 8-row rationalization table for skipping testing, and has extensive sections that could be dramatically compressed. The token efficiency section ironically violates its own advice.

1 / 3

Actionability

The skill provides concrete YAML frontmatter examples, directory structures, and a detailed checklist, which are actionable. However, much of the content is philosophical/motivational rather than executable (e.g., the Iron Law repetitions, anti-pattern narratives). The actual skill creation steps are buried in verbose surrounding text, and the testing methodology defers to another file rather than providing concrete commands.

2 / 3

Workflow Clarity

The RED-GREEN-REFACTOR workflow is clearly sequenced and the final checklist provides explicit steps. However, the validation steps are vague ('run scenarios WITH skill - verify agents now comply') without concrete commands or criteria for what 'comply' means. The workflow is also scattered across multiple sections rather than presented as one clear sequence, making it harder to follow.

2 / 3

Progressive Disclosure

The skill references external files appropriately (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot) and correctly uses cross-references instead of @ links. However, the main SKILL.md itself is monolithic with too much inline content that could be split out - the CSO section, the bulletproofing section, and the testing section are each substantial enough to warrant separate files.

2 / 3

Total

7

/

12

Passed

Validation

90%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (656 lines); consider splitting into references/ and linking

Warning

Total

10

/

11

Passed

Repository
aaddrick/claude-desktop-debian
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.