CtrlK
BlogDocsLog inGet started
Tessl Logo

write-a-skill

Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.

84

Quality

80%

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/productivity/write-a-skill/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

89%

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 is a solid description that clearly communicates both what the skill does and when to use it, with good trigger terms. Its main weakness is that the 'what' portion uses somewhat abstract concepts ('proper structure', 'progressive disclosure', 'bundled resources') rather than listing concrete actions. Overall it performs well for skill selection purposes.

Suggestions

Replace abstract terms like 'proper structure' and 'progressive disclosure' with more concrete actions, e.g., 'Generate YAML frontmatter, write step-by-step instructions, and bundle example resources into skill markdown files.'

DimensionReasoningScore

Specificity

Names the domain (agent skills) and some actions ('create new agent skills with proper structure, progressive disclosure, and bundled resources'), but the terms 'proper structure', 'progressive disclosure', and 'bundled resources' are somewhat abstract rather than concrete observable actions like 'generate YAML frontmatter' or 'create markdown files with examples'.

2 / 3

Completeness

Clearly answers both 'what' (create new agent skills with proper structure, progressive disclosure, and bundled resources) and 'when' (Use when user wants to create, write, or build a new skill) with an explicit 'Use when...' clause.

3 / 3

Trigger Term Quality

Includes natural trigger terms users would say: 'create', 'write', 'build', 'new skill'. These are common verbs a user would naturally use when requesting skill creation. The term 'agent skills' is also specific and relevant.

3 / 3

Distinctiveness Conflict Risk

The description targets a very specific niche—creating agent skills—which is unlikely to conflict with other skills. The combination of 'agent skills', 'progressive disclosure', and 'bundled resources' makes this clearly distinguishable.

3 / 3

Total

11

/

12

Passed

Implementation

70%

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

This is a solid meta-skill for creating new skills, with excellent workflow clarity and progressive disclosure. Its main weaknesses are moderate verbosity in the description requirements section and the use of placeholder text in the template rather than a fully concrete, filled-in example. The review checklist is a strong validation mechanism.

Suggestions

Replace placeholder text in the SKILL.md template (e.g., '[Minimal working example]') with a concrete, filled-in example of a simple skill to make the template fully actionable.

Tighten the 'Description Requirements' section by removing the explanation of how the agent uses descriptions internally—just state the format rules and show the good/bad examples.

DimensionReasoningScore

Conciseness

Mostly efficient but includes some unnecessary explanation. The 'Description Requirements' section over-explains what a description is and how the agent uses it, which is somewhat verbose. The 'Good example' vs 'Bad example' comparison for descriptions is helpful but could be tighter. The 'When to Add Scripts' and 'When to Split Files' sections are lean and well-done.

2 / 3

Actionability

Provides a clear template and directory structure, which is concrete and useful. However, the SKILL.md template contains placeholder text like '[Minimal working example]' and '[Step-by-step processes with checklists]' rather than filled-in executable examples. The process steps are more of a conversational workflow than copy-paste-ready instructions.

2 / 3

Workflow Clarity

The three-step process (Gather requirements → Draft → Review) is clearly sequenced with specific sub-items at each stage. The review checklist at the end provides an explicit validation checkpoint. For a skill-creation workflow, this level of structure is appropriate and includes feedback loops (review with user, verify against checklist).

3 / 3

Progressive Disclosure

The skill is well-organized with clear sections that progress from process to structure to template to specific guidance topics. The template itself demonstrates progressive disclosure by showing how to reference REFERENCE.md. Content is appropriately split into logical sections without being monolithic, and no bundle files are needed for this self-contained meta-skill.

3 / 3

Total

10

/

12

Passed

Validation

100%

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

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
mattpocock/skills
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.