writing-skills

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

1.86x

Quality

62%

Does it follow best practices?

Impact

93%

1.86x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

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.

This description focuses entirely on when to use the skill but fails to explain what the skill actually does. It lacks concrete actions, specific capabilities, and sufficient trigger terms. The description would benefit significantly from explaining what skill creation/editing involves and adding more natural keywords users might use.

Suggestions

Add a 'what' clause describing concrete capabilities like 'Generates SKILL.md files with proper YAML frontmatter, validates skill syntax, and provides templates for new skills'

Expand trigger terms to include variations like 'SKILL.md', 'skill file', 'skill template', 'write a skill', 'new skill'

Specify what 'verifying skills work' means concretely, such as 'validates frontmatter schema, checks for required fields, tests skill matching'

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	Has a 'Use when...' clause addressing when to use it, but the 'what does this do' portion is entirely missing. The description only specifies triggers without explaining capabilities.	2 / 3
Trigger Term Quality	Contains some relevant keywords ('skills', 'creating', 'editing', 'deployment') but misses common variations users might say like 'SKILL.md', 'skill file', 'write a skill', 'test skill', or 'skill template'.	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 involving file creation or editing.	2 / 3
	Total	7 / 12 Passed

Implementation

85%

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

This is a strong, comprehensive skill that successfully applies TDD principles to documentation creation. Its main strengths are excellent workflow clarity with explicit validation checkpoints and highly actionable guidance with concrete examples. The primary weakness is verbosity - some concepts are repeated and the document could be tightened by 20-30% without losing clarity.

Suggestions

Consolidate the Iron Law section - it's stated in full twice (once in TDD Mapping, once standalone) and referenced multiple times

Move the detailed 'Common Rationalizations for Skipping Testing' table to a separate reference file since it's heavy reference material (100+ lines of rationalization content total)

Trim the CSO section examples - currently shows 6+ bad/good pairs when 2-3 would suffice to illustrate the pattern

Dimension	Reasoning	Score
Conciseness	The skill is comprehensive but verbose at ~2500 words. Contains some redundancy (TDD mapping repeated multiple times, Iron Law stated twice) and explanatory content that could be trimmed. However, most content earns its place given the complexity of the topic.	2 / 3
Actionability	Provides concrete, executable guidance throughout: specific directory structures, YAML frontmatter examples, code blocks for verification commands, complete checklists with TodoWrite instruction, and clear good/bad examples for every concept.	3 / 3
Workflow Clarity	Excellent workflow clarity with explicit RED-GREEN-REFACTOR phases, detailed checklists with validation checkpoints, clear sequencing (baseline → write → test → refactor), and explicit 'STOP' instruction before moving to next skill. Feedback loops are well-defined.	3 / 3
Progressive Disclosure	Well-structured with clear overview, appropriate cross-references to related skills (test-driven-development, testing-skills-with-subagents, persuasion-principles), and explicit guidance on when to use inline vs separate files. Navigation is clear with descriptive section headers.	3 / 3
	Total	11 / 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

Repository: projectbluefin/dakota
Commit: f062bf8

Reviewed: 11 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.