writing-skills

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

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/writing-skills/SKILL.md

The canonical home for this skill is writing-skills in obra/superpowers

Quality

Content

70%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 thorough, well-sequenced meta-skill with strong checklists, validation loops, and concrete examples, but it is longer and more repetitive than its own token-efficiency guidance recommends, and it does not practice the progressive disclosure it preaches: key references point to files that are absent from the bundle.

Suggestions

Deduplicate the TDD mapping (currently in prose, table, and the RED-GREEN-REFACTOR section) and consolidate the repeated 'description = when, not what' explanations.

Move the inlined research/methodology material (e.g. persuasion-principles, testing methodology) into the referenced files and ensure those files actually exist in the bundle, or remove the references.

Trim or relocate the long YAML good/bad example blocks to a separate reference to reduce SKILL.md token load, matching the skill's own <200/<500 word targets.

Dimension	Reasoning	Score
Conciseness	The ~655-line body repeats several ideas (TDD mapping in prose, table, and RED-GREEN-REFACTOR; the 'description = when not what' point restated multiple times), so while mostly efficient, there is noticeable redundancy that could be tightened.	3 / 5
Actionability	Provides concrete, copy-ready guidance: authoring checklists, before/after YAML examples, directory structures, and executable commands (wc -w, render-graphs.js); minor gaps since the core examples are process templates rather than fully runnable code.	4 / 5
Workflow Clarity	Clear RED-GREEN-REFACTOR sequence with explicit validation checkpoints and feedback loops ('Run scenarios WITHOUT skill', 'verify agents now comply', 'Re-test until bulletproof'), plus a destructive-operation rule ('Delete it. Start over.') with enforcement detail.	5 / 5
Progressive Disclosure	It is a monolithic ~655-line file that inlines material its own rules say belongs in separate files (persuasion research, testing methodology), and references several bundle files (anthropic-best-practices.md, graphviz-conventions.dot, testing-skills-with-subagents.md, render-graphs.js, persuasion-principles.md) that are not present in the bundle.	3 / 5
	Total	15 / 20 Passed

Description

75%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 clear, third-person, trigger-focused description that names concrete authoring activities and opens with 'Use when...'. It answers both what and when without over-claiming, though it could add symptom-driven triggers and synonyms for stronger discovery.

Suggestions

Add symptom-oriented triggers users would voice (e.g. 'when a skill needs to be tested with subagents before deployment', 'when documenting a reusable technique').

Include a couple of natural synonyms to broaden keyword coverage (e.g. 'authoring', 'documenting', 'skill verification').

Make the 'when' clause more context-specific (e.g. name 'before deployment' situations) to sharpen distinctiveness.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ('creating new skills, editing existing skills, or verifying skills work before deployment'); these are activities rather than granular operations, with minor gaps in coverage of the full authoring workflow.	4 / 5
Completeness	Explicit 'Use when...' clause answers when, and the listed actions answer what; both are present though 'when' could be more specific about symptoms or contexts.	4 / 5
Trigger Term Quality	Includes natural phrases a user would say ('creating new skills', 'editing existing skills', 'verifying skills'); good coverage but limited synonyms or variations.	4 / 5
Distinctiveness Conflict Risk	Targets a fairly distinct niche (skill authoring/verification) with only minor overlap risk against a hypothetical skill-verification skill.	4 / 5
	Total	16 / 20 Passed

Validation

93%

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 — 15 / 16 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	15 / 16 Passed

Repository: roman01la/skills-agents
Path: skills/writing-skills/SKILL.md
Commit: aa6f9d3

Reviewed: 8 days 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.