agentleFS
vbonkvbonk/repo-template/.claude/skills/skill-validator/SKILL.md

skill-validator

Skill8 starsChanged 3 months agoMITView on GitHub

Validate and optimize existing Claude Code skills. Test discovery, check YAML frontmatter, analyze descriptions, suggest improvements, verify file structure, generate test phrases. Use when skills aren't being discovered, validating new skills, debugging skill issues, optimizing discoverability, or testing skill installation. Triggers on "validate skill", "test skill", "skill not found", "skill not working", "debug skill".

19 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use fetch-library-docs, browsing-with-playwright and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Rehan-Ul-HaqSkill

    fetch-library-docs

    Fetches official documentation for external libraries and frameworks (React, Next.js, Prisma, FastAPI, Express, Tailwind, MongoDB, etc.) with 60-90% token savings via content-type filtering. Use this skill when implementing features using library APIs, debugging library-specific errors, troubleshooting configuration issues, installing or setting up frameworks, integrating third-party packages, upgrading between library versions, or looking up correct API patterns and best practices. Triggers automatically during coding work - fetch docs before writing library code to get correct patterns, not after guessing wrong.

    Also in 6 projects that use this

  • mjunaidcaSkill

    browsing-with-playwright

    Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction. NOT when only fetching static content (use curl/wget instead).

    Also in 5 projects that use this

  • muhammad-anas35Skill

    skill-creator-pro

    Creates production-grade, reusable skills that extend Claude's capabilities. This skill should be used when users want to create a new skill, improve an existing skill, or build domain-specific intelligence. Gathers context from codebase, conversation, and authentic sources before creating adaptable skills.

    Also in 7 projects that use this

  • dazuckSkill

    interview

    Interview me about a plan to flesh out requirements before implementation. Asks non-obvious questions one at a time until all ambiguities are resolved.

    Also in 4 projects that use this

  • JetBrainsSkill

    doc-coauthoring

    Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

    Also in 4 projects that use this

  • GoogleSkill

    internal-comms

    A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

    Also in 4 projects that use this

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 17 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Check that the skill follows proper structure:

    line 29
  2. Distinctive:

    When optimizing descriptions, apply this formula:

    line 225
  3. Distinctive:

    No errors, just doesn't activate

    line 296
  4. Very specific:

    Check capitalization: SKILL.md not skill.md

    line 310
  5. Distinctive:

    Add specific keywords to description

    line 343
  6. Distinctive:

    Add use case triggers

    line 345
  7. Distinctive:

    When asked to optimize a skill, follow this workflow:

    line 378
  8. Distinctive:

    Before marking a skill as validated:

    line 419

“Common” is measured: kept by at least 6 in 10 of the 17 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill Validator

Comprehensive skill validation and optimization system that tests discovery, validates structure, and improves discoverability.

Quick Start

# Validate a skill
/skill-validator my-skill-name

# Optimize description only
/skill-validator --optimize my-skill-name

# Full test report
/skill-validator --full my-skill-name

Validation Process

Step 1: File Structure Validation

Check that the skill follows proper structure:

Required:

  • Skill is in .claude/skills/ or ~/.claude/skills/
  • Directory name is kebab-case
  • SKILL.md file exists (exactly this name, case-sensitive)
  • YAML frontmatter is present and valid

Common Issues:

ProblemSolution
skill.md (lowercase)Rename to SKILL.md
Wrong directory locationMove to .claude/skills/
Missing frontmatter ---Add YAML delimiters
No name: fieldAdd required field
No description: fieldAdd required field

Correct Structure:

.claude/skills/my-skill/
├── SKILL.md              # Required (exact case!)
├── reference.md          # Optional
├── examples/             # Optional
└── templates/            # Optional

Step 2: YAML Frontmatter Validation

Parse and validate the YAML:

Required Fields:

---
name: [Must be present]
description: [Must be present and not empty]
---

Common YAML Errors:

# Missing colon
name My Skill  # FIX: name: My Skill

# Wrong spacing
name:My Skill  # FIX: name: My Skill

# Special chars not quoted
description: Contains: colons  # FIX: "Contains: colons"

# Missing closing ---
---
name: My Skill
description: Things
# FIX: Add closing ---

Step 3: Description Quality Analysis

Analyze the description for discoverability:

Check for presence of:

ElementWeightExample
Action verbs+20%analyze, generate, transform, validate
File types+20%.js, .ts, .py, .md, .json
Use case triggers+20%"Use when...", problem scenarios
Domain keywords+20%API, database, test, security
Specific capabilities+10%concrete features listed
Optimal length+10%40-100 words

Scoring:

ScoreQualityDiscovery Likelihood
90-100%ExcellentVery likely discovered
70-89%GoodLikely discovered
50-69%FairSometimes discovered
30-49%PoorRarely discovered
0-29%CriticalWon't be discovered

Step 4: Generate Test Phrases

Based on the skill's description, generate phrases to test discovery:

Test Categories:

  1. Direct Triggers (HIGH confidence)
    • Phrases using exact keywords from description
    • File type mentions
    • Domain-specific terms
  2. Indirect Triggers (MEDIUM confidence)
    • Problem descriptions the skill solves
    • Related workflows
    • Semantic equivalents
  3. Should NOT Trigger (verify scope)
    • Different domain requests
    • Different file types
    • Unrelated problems

Step 5: Generate Recommendations

Provide actionable improvements based on findings.


Output Format

# Skill Validation Report

## Skill: [Skill Name]
**Location:** `~/.claude/skills/[skill-directory]/SKILL.md`
**Date:** [Current date]

---

## File Structure: [PASSED/WARNING/FAILED]

- [Check 1]: [result]
- [Check 2]: [result]
- [Check 3]: [result]

---

## YAML Frontmatter: [PASSED/FAILED]

```yaml
---
name: [Extracted name]
description: [Extracted description]
---

Validation:

  • Required fields: [result]
  • YAML syntax: [result]
  • Description length: [result]

Description Quality: [Score]% ([Rating])

Present:

  • element: [found in description]

Missing:


Test Phrases

Direct Triggers (HIGH confidence)

  1. "[Phrase 1]"
  2. "[Phrase 2]"
  3. "[Phrase 3]"

Indirect Triggers (MEDIUM confidence)

  1. "[Phrase 4]"
  2. "[Phrase 5]"

Should NOT Trigger

  1. "[Phrase 6]" - Wrong domain
  2. "[Phrase 7]" - Different file type

Recommendations

Critical (Must Fix)

Suggested Improvements


Summary

Overall Status: [READY/NEEDS IMPROVEMENT/CRITICAL ISSUES] Discovery Confidence: [High/Medium/Low]

Next Steps:

  1. [Action 1]
  2. [Action 2]

---

## Description Optimization

When optimizing descriptions, apply this formula:

[Action verbs] + [Specific capabilities] + [File types/formats] + [Use case triggers]


### Optimization Patterns

#### Pattern 1: Too Vague → Specific

**Before:**
```yaml
description: Helps with code analysis

Problems:

  • No action verbs
  • "Helps" is weak
  • "Code" is too broad
  • No file types
  • No use cases

After:

description: Analyze JavaScript and TypeScript code for complexity, maintainability, and code smells. Detect anti-patterns, measure cyclomatic complexity, suggest refactoring. Works with .js, .ts, .jsx, .tsx files. Use when reviewing code quality, performing code reviews, or investigating technical debt.

Pattern 2: Missing File Types → Explicit Extensions

Before:

description: Converts configuration files between different formats

After:

description: Convert configuration files between JSON, YAML, TOML, and INI formats. Transform .json to .yaml, .toml to .json, .ini to .yaml. Preserve structure, handle edge cases, validate output. Use when migrating configs, converting between .json/.yaml/.toml/.ini files.

Pattern 3: No Use Cases → Explicit Triggers

Before:

description: Generates API documentation from code

After:

description: Generate API documentation from TypeScript, Python, or Java code. Create Markdown, HTML, or OpenAPI specs from code comments and type definitions. Works with .ts, .py, .java files. Use when documenting APIs, need OpenAPI specs, creating README files.

Pattern 4: Too Broad → Focused Scope

Before:

description: Helps with testing in any programming language

After:

description: Generate unit tests for JavaScript and TypeScript functions using Jest and Vitest. Create test cases, mock dependencies, assert behaviors. Works with .js, .ts files. Use when writing tests, need test coverage, or practicing TDD with Jest/Vitest.

Common Discovery Problems

Problem 1: Skill File Not Found

Symptoms:

  • Skill should work but Claude doesn't see it
  • No errors, just doesn't activate

Diagnosis:

# Check if file exists
ls -la .claude/skills/my-skill/SKILL.md

# Common issues:
# - .claude/skill/ instead of .claude/skills/
# - skill.md instead of SKILL.md

Fix:

  1. Verify path: .claude/skills/[skill-name]/SKILL.md
  2. Check capitalization: SKILL.md not skill.md

Problem 2: YAML Parsing Error

Symptoms:

  • Skill file exists but doesn't work
  • Frontmatter looks correct

Diagnosis:

# Check for:
name My Skill     # Missing colon
name:My Skill     # Missing space
---
name: My Skill
[No closing ---]  # Missing delimiter

Fix:

---
name: My Skill
description: "If description has colons: use quotes"
---

Problem 3: Description Too Vague

Symptoms:

  • Skill exists, YAML valid, but never discovered
  • Works when explicitly invoked

Fix:

  • Add specific keywords to description
  • Include file types
  • Add use case triggers
  • Run /skill-validator --optimize

Problem 4: Skill Too Broad

Symptoms:

  • Skill activates when it shouldn't
  • Gets invoked for unrelated tasks

Fix:

  • Narrow description scope
  • Add qualifying context
  • Be specific about domain

Quick Validation Commands

# Check file exists (correct case)
ls -la ~/.claude/skills/[name]/SKILL.md

# View frontmatter
head -15 ~/.claude/skills/[name]/SKILL.md

# Count description elements
# (Run this skill for automated analysis)

Interactive Optimization

When asked to optimize a skill, follow this workflow:

  1. Read current SKILL.md
  2. Analyze description for missing elements
  3. Ask clarifying questions:
    • "What file types does this skill work with?"
    • "What specific capabilities does it have?"
    • "When would someone naturally ask for this?"
    • "What problems does it solve?"
  4. Generate optimized description with before/after comparison
  5. Provide test phrases for verification

Anti-Patterns to Detect

Marketing Speak

# BAD: No concrete capabilities
description: The ultimate solution for all your code analysis needs.

Feature List Without Use Cases

# BAD: No "when to use"
description: Has many features including analysis, generation, and more.

Acronyms Without Expansion

# BAD: User might not know "OAS"
description: Works with OAS and RAML specs.
# GOOD: Include full names
description: Works with OpenAPI (OAS) and RAML specifications.

Validation Checklist

Before marking a skill as validated:

File Structure

  • Skill directory in .claude/skills/ or ~/.claude/skills/
  • Directory name is kebab-case
  • SKILL.md file exists (correct capitalization)

YAML Frontmatter

  • Starts with ---
  • Ends with ---
  • name: field present
  • description: field present and not empty
  • Valid YAML syntax

Description Quality

  • Contains action verbs
  • Mentions file types (if applicable)
  • Includes use case triggers
  • Has domain-specific keywords
  • Is 40-100 words (optimal)
  • No marketing fluff

Discovery Test

  • Test with direct trigger phrase - skill activates
  • Test with indirect phrase - skill may activate
  • Test with unrelated phrase - skill does NOT activate

Version: 1.0.0 Created: 2026-01-23 Replaces: skill-description-optimizer, skill-discovery-tester

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.