CtrlK
BlogDocsLog inGet started
Tessl Logo

writing-skills

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

39

Quality

37%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./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 functions primarily as a 'when' clause without adequately explaining 'what' the skill actually does. It lacks concrete actions (e.g., generating YAML frontmatter, validating skill structure, testing skill matching) and relies on vague verbs. The domain of 'skills' is somewhat distinctive but insufficiently defined to clearly differentiate from general file editing or creation skills.

Suggestions

Add explicit 'what' capabilities such as 'Generates skill markdown files with proper YAML frontmatter, validates skill structure, and tests skill descriptions for quality'.

Include more natural trigger terms users might say, such as 'skill.md', 'write a skill', 'skill file', 'skill template', or 'skill format'.

Clarify the domain by specifying these are Claude/MCP skills in markdown format to reduce conflict risk with generic editing skills.

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 addresses 'when' with 'Use when creating new skills, editing existing skills, or verifying skills work before deployment', but the 'what' is only implied through the trigger conditions rather than explicitly stated as concrete capabilities.

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', 'write a skill', 'test a skill', 'skill file', 'YAML frontmatter', or 'markdown skill'.

2 / 3

Distinctiveness Conflict Risk

The term 'skills' provides some specificity to a niche domain, but without more detail about what kind of skills (e.g., Claude skills, .md skill files), it could overlap with general editing or creation tasks.

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 skill is comprehensive in scope but severely undermined by verbosity—it repeats core concepts (Iron Law, no exceptions, TDD mapping) multiple times and includes extensive motivational content that Claude doesn't need. The actionable content (frontmatter spec, directory structure, checklist) is solid but buried under philosophical framing. The skill would benefit enormously from being split into a concise SKILL.md overview with heavy reference material in separate files.

Suggestions

Cut content by 60%+: Remove the rationalization tables, repeated Iron Law statements, and TDD philosophy explanations. Claude understands TDD—focus on the skill-specific adaptation only.

Split into multiple files: Move CSO guidance, bulletproofing patterns, testing methodology, and anti-patterns into separate reference files, keeping SKILL.md as a concise overview with the checklist and core structure.

Make the testing workflow concrete: Instead of 'run scenarios WITH skill - verify agents now comply', provide a specific example of a pressure scenario, expected baseline failure, and what passing looks like.

Remove redundant examples: The CSO section has 8+ good/bad YAML examples that could be reduced to 2-3 representative ones.

DimensionReasoningScore

Conciseness

This skill is extremely verbose at ~2500+ words. It explains concepts Claude already knows (what TDD is, what a PDF is analogous to explaining what a skill is), repeats the same points multiple times (the Iron Law is stated in at least 3 places, the 'no exceptions' pattern repeated), includes an 8-row rationalization table that belabors obvious points, and has extensive sections that could be compressed dramatically. The CSO section alone contains multiple redundant examples showing good vs bad patterns.

1 / 3

Actionability

The skill provides some concrete guidance like the YAML frontmatter structure, directory layout examples, and the checklist. However, much of the content is philosophical/motivational rather than executable ('If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing'). The actual skill creation steps are buried under layers of TDD philosophy. The checklist at the end is actionable but could be more concrete with specific commands.

2 / 3

Workflow Clarity

The RED-GREEN-REFACTOR workflow is clearly sequenced and the final checklist provides good structure. However, validation checkpoints are vague ('run scenarios WITH skill - verify agents now comply') without specifying how to verify or what passing looks like concretely. The testing methodology is deferred to an external file (testing-skills-with-subagents.md) which isn't provided, creating a gap in the workflow.

2 / 3

Progressive Disclosure

The skill references several external files (anthropic-best-practices.md, testing-skills-with-subagents.md, persuasion-principles.md, graphviz-conventions.dot, render-graphs.js) but none are provided in the bundle. The main document itself is monolithic with too much inline content that could be split out (the entire CSO section, the bulletproofing section, the testing section). The structure has clear headings but the sheer volume undermines progressive disclosure.

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 (671 lines); consider splitting into references/ and linking

Warning

Total

10

/

11

Passed

Repository
lucianghinda/superpowers-ruby
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.