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 provides reasonable 'when to use' guidance but almost entirely lacks a 'what it does' component — it doesn't describe any concrete capabilities like generating YAML frontmatter, validating skill structure, or creating markdown templates. The trigger terms are moderately useful but could be more specific to the skill file format and ecosystem.

Suggestions

Add concrete capability descriptions before the 'Use when' clause, e.g., 'Generates skill markdown files with proper YAML frontmatter, validates skill structure, and tests skill behavior.'

Expand trigger terms to include format-specific keywords like 'SKILL.md', 'skill file', 'skill template', 'frontmatter', or 'skill definition'.

Clarify what 'verifying skills work before deployment' actually entails — does it run tests, validate syntax, check for required fields?

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 answers 'when' with explicit trigger conditions ('Use when creating new skills, editing existing skills, or verifying skills'), but the 'what does this do' part is essentially absent — it only restates the triggers without describing the actual capabilities or actions the skill performs.

2 / 3

Trigger Term Quality

Includes some relevant keywords like 'skills', 'creating new skills', 'editing existing skills', and 'deployment' that users might naturally say. However, it misses variations like 'skill.md', 'SKILL file', 'skill template', 'skill frontmatter', or 'skill testing'.

2 / 3

Distinctiveness Conflict Risk

The term 'skills' provides some specificity to a niche domain, but without clarifying what kind of skills (e.g., SKILL.md files, Claude skills), it could overlap with general coding or documentation skills. The word 'deployment' is also quite generic.

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 the TDD-for-documentation concept, CSO optimization, and the detailed checklist. Its greatest weakness is that it violates its own principles—it advocates for token efficiency and conciseness while being extremely long and repetitive, and it advocates for testing-first while providing no concrete, executable test examples. The skill would benefit enormously from practicing what it preaches: compressing to ~500 words with heavy reference material in separate files.

Suggestions

Reduce the main SKILL.md to under 500 words (as the skill itself recommends) by moving the rationalization tables, anti-patterns, CSO details, and testing methodology into separate reference files (e.g., cso-guide.md, rationalization-patterns.md, testing-guide.md)

Add a concrete, executable example of running a baseline test with a subagent—show the actual command/prompt used, the expected failing output, and what 'passing' looks like, rather than describing the concept abstractly

Remove redundant explanations: the TDD mapping table, the prose explanation of TDD, and the 'Bottom Line' section all say the same thing three times—pick one representation

Add explicit validation commands to the checklist (e.g., 'wc -w SKILL.md' to verify word count, a concrete subagent invocation template) to match the workflow_clarity standards the skill itself defines

DimensionReasoningScore

Conciseness

This skill is extremely verbose at ~2500+ words. It explains concepts Claude already knows (what TDD is, what a PDF is metaphorically, basic rationalization psychology), repeats the same points multiple times (the Iron Law appears twice, the 'no exceptions' pattern repeats, the TDD mapping table duplicates the prose explanation), and includes extensive rationalization tables and anti-pattern sections that could be dramatically compressed. The irony is that the skill itself advocates for token efficiency (<500 words for most skills) while massively exceeding that target.

1 / 3

Actionability

The skill provides some concrete guidance (YAML frontmatter examples, directory structure, naming conventions, checklist items) but lacks executable code for the core workflow. The testing methodology references an external file (@testing-skills-with-subagents.md) rather than providing concrete test commands. The 'how to actually run a baseline test with a subagent' is never shown with a concrete, copy-paste-ready example—it stays at the conceptual level.

2 / 3

Workflow Clarity

The RED-GREEN-REFACTOR cycle is clearly sequenced and the final checklist provides good structure. However, validation checkpoints are implicit rather than explicit—there's no concrete 'run this command to verify' step. The checklist says 'Run scenarios WITH skill - verify agents now comply' but doesn't specify how to verify compliance or what passing looks like. For a skill about testing/verification, the absence of concrete validation commands is a notable gap.

2 / 3

Progressive Disclosure

The skill references several external files (testing-skills-with-subagents.md, anthropic-best-practices.md, persuasion-principles.md, graphviz-conventions.dot, render-graphs.js) which suggests good intent for progressive disclosure. However, no bundle files were provided, so we can't verify these references resolve. The main SKILL.md itself is monolithic—much of the content (rationalization tables, anti-patterns, CSO details, flowchart usage) could be split into separate reference files, following the skill's own advice about keeping frequently-loaded skills under 500 words.

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.