create-skill

Guide for creating effective skills following best practices. Use when creating or updating skills that extend agent capabilities.

Quality

62%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Quality

Discovery

67%

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 has good structure with an explicit 'Use when' clause that clearly defines the trigger scenario. However, it lacks specific concrete actions that would help Claude understand exactly what guidance this skill provides, and the trigger terms could be more comprehensive to capture natural user language variations.

Suggestions

Add specific concrete actions like 'write YAML frontmatter, define trigger terms, structure skill content, follow naming conventions'

Expand trigger terms to include variations users might say: 'SKILL.md', 'skill file', 'new skill', 'skill template', 'teach Claude'

Dimension	Reasoning	Score
Specificity	Names the domain ('creating effective skills') and mentions some actions ('creating or updating skills'), but lacks concrete specific actions like 'write YAML frontmatter', 'define trigger terms', or 'structure skill files'.	2 / 3
Completeness	Clearly answers both what ('Guide for creating effective skills following best practices') and when ('Use when creating or updating skills that extend agent capabilities') with an explicit trigger clause.	3 / 3
Trigger Term Quality	Includes relevant keywords like 'skills' and 'agent capabilities', but misses common variations users might say such as 'SKILL.md', 'skill file', 'new skill', 'skill template', or 'extend Claude'.	2 / 3
Distinctiveness Conflict Risk	Somewhat specific to skill creation, but 'agent capabilities' and 'best practices' are generic enough that it could potentially overlap with other meta-skills or documentation guides.	2 / 3
	Total	9 / 12 Passed

Implementation

57%

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

This meta-skill about creating skills demonstrates good progressive disclosure structure but falls short on actionability and conciseness. It explains concepts at a high level without providing concrete, executable examples of skill content. The irony is that a skill about creating skills should exemplify best practices more directly through demonstration rather than description.

Suggestions

Add a concrete, minimal example of a complete SKILL.md (frontmatter + body) that demonstrates the principles inline rather than only referencing external files

Remove conceptual explanations like 'Think of them as onboarding guides' - Claude understands the concept; focus on the specific implementation details

Add a numbered workflow with validation checkpoints: 1. Create structure, 2. Write frontmatter, 3. Validate line count, 4. Test with target models, etc.

Replace the 'What Skills Provide' list with a single sentence - the categories are self-evident from the rest of the document

Dimension	Reasoning	Score
Conciseness	The skill includes some unnecessary explanations that Claude would already know (e.g., 'Think of them as onboarding guides', explaining what skills provide at a conceptual level). The content could be tightened by removing meta-explanations and focusing on actionable guidance.	2 / 3
Actionability	Provides structural guidance and principles but lacks concrete, executable examples. The 'Core Principles' section describes concepts rather than showing specific code or commands. No copy-paste ready examples of actual skill content are provided inline.	2 / 3
Workflow Clarity	The three-level loading system and skill structure are described but there's no step-by-step workflow for actually creating a skill. Missing explicit validation steps or checkpoints for verifying skill quality before deployment.	2 / 3
Progressive Disclosure	Excellent use of progressive disclosure - the skill practices what it preaches. Clear overview with well-signaled one-level-deep references to detailed documentation in the references/ directory. Content is appropriately split.	3 / 3
	Total	9 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: siviter-xyz/dot-agent
Commit: 3376255

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.