writing-skills

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

Install with Tessl CLI

npx tessl i github:shousper/claude-kit --skill writing-skills

What are skills?

1.77x

Quality

58%

Does it follow best practices?

Impact

94%

1.77x

Average score across 3 eval scenarios

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/writing-skills/SKILL.md

SKILL.md

Review

Evals

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.

This description focuses entirely on when to use the skill but completely omits what the skill actually does. While it correctly uses a 'Use when...' clause, the lack of concrete capabilities (e.g., 'generates skill templates', 'validates YAML frontmatter', 'tests skill execution') makes it difficult for Claude to understand the skill's actual functionality and distinguish it from other skills.

Suggestions

Add concrete actions describing what the skill does, e.g., 'Generates skill templates, validates YAML frontmatter, and tests skill execution against sample inputs.'

Include more natural trigger terms users might say: 'SKILL.md', 'skill file', 'skill template', 'markdown skill', 'test my skill'

Specify the domain more clearly to reduce conflict risk, e.g., 'Claude Code skills' or 'agent skills' rather than just 'skills'

Dimension	Reasoning	Score
Specificity	The description uses vague language like 'creating', 'editing', and 'verifying' without specifying concrete actions. It doesn't explain what skills are, what creating/editing involves, or what verification entails.	1 / 3
Completeness	The description provides a 'Use when...' clause addressing when to use it, but the 'what does this do' component is entirely missing. There's no explanation of what capabilities or actions the skill provides.	2 / 3
Trigger Term Quality	Contains some relevant keywords ('skills', 'deployment') but lacks natural variations users might say like 'skill file', 'SKILL.md', 'skill template', or 'test skill'. The term 'skills' is somewhat generic.	2 / 3
Distinctiveness Conflict Risk	The term 'skills' provides some specificity to this domain, but 'creating', 'editing', and 'verifying' are generic actions that could overlap with many other skills. Without more specific triggers, it could conflict with general editing or testing skills.	2 / 3
	Total	7 / 12 Passed

Implementation

77%

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 meta-skill that effectively teaches TDD-based skill creation with strong actionability and workflow clarity. The main weakness is verbosity - at 2000+ words it exceeds its own recommended limits (<500 words for non-getting-started skills) and contains some redundancy. The progressive disclosure is adequate but could better model the conciseness it preaches.

Suggestions

Reduce redundancy by consolidating the TDD mapping table and Iron Law sections - the same concepts appear multiple times

Move the 'Common Rationalizations' and 'Bulletproofing Skills' sections to a separate reference file to reduce main skill length

Apply the skill's own token efficiency techniques: compress examples, eliminate repeated explanations of TDD principles

Consider splitting into a quick-start SKILL.md (<200 words) with references to detailed guides for testing methodology, CSO optimization, and anti-patterns

Dimension	Reasoning	Score
Conciseness	The skill is comprehensive but verbose at ~2000+ words. Contains some redundancy (TDD mapping repeated multiple times, rationalization tables appear twice) and explanatory content that could be tightened. However, much content is genuinely necessary for a meta-skill about creating skills.	2 / 3
Actionability	Provides concrete, executable guidance throughout: specific YAML frontmatter examples, directory structures, code examples for render-graphs.js, explicit checklists with TodoWrite instructions, and copy-paste ready templates for skill structure. The good/bad examples are particularly actionable.	3 / 3
Workflow Clarity	Excellent workflow clarity with explicit RED-GREEN-REFACTOR cycle mapped to skill creation. Clear validation checkpoints (baseline testing before writing, re-testing after each change), explicit 'STOP' section preventing batch creation without testing, and comprehensive checklist with phases clearly delineated.	3 / 3
Progressive Disclosure	References external files appropriately (testing-skills-with-subagents.md, persuasion-principles.md, graphviz-conventions.dot, anthropic-best-practices.md) but the main document is quite long. Some sections like 'Common Rationalizations' and 'Bulletproofing Skills' could potentially be split out. The cross-referencing guidance is good but the skill itself doesn't fully follow its own advice about token efficiency.	2 / 3
	Total	10 / 12 Passed

Validation

90%

Warnings & errors only

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

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (656 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

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.