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
- Ramya-Meyyazhagan/skill_validatortheir own version, first seen Nov 15, 2026
- Anvil-Code/skill-validatortheir own version, first seen Nov 15, 2026
- shawnclybor/clybor-claude-toolingtheir own version, first seen Nov 8, 2026
- AbdulSamad94/Personal-AI-Employeetheir own version, first seen Nov 8, 2026
- gurupak/claude-skillstheir own version, first seen Oct 25, 2026
- AlessioScarfone/skillstheir own version, first seen Oct 15, 2026
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-HaqSkillfetch-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
mjunaidcaSkillbrowsing-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-anas35Skillskill-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
dazuckSkillinterview
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
JetBrainsSkilldoc-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
GoogleSkillinternal-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
Other versions19 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 19
- panaversity/claude-code-skills-lab★ 57same name
- AbdulSamad94/Personal-AI-Employee★ 8same name
- Rehan-Ul-Haq/my-skills★ 8same name
- shawnclybor/clybor-claude-tooling★ 6same name
- sheikh-mohammad/agent-factory-claude-skills★ 6same name
- Anvil-Code/skill-validator★ 4same name
- localSummer/skills★ 4same name
- shipshitgames/skills★ 2same name
- studiobrittany/studio-brittany-ai★ 2same name
- coreline-ai/validation-skill-base★ 1same name
9 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- cotSkill
- dependency-healthSkill
- hibernateSkill
- repo-docsSkill
- skill-builderSkill
- task-cleanupSkill
- template-upgradeSkill
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
- Distinctive: line 29
Check that the skill follows proper structure:
- Distinctive: line 225
When optimizing descriptions, apply this formula:
- Distinctive: line 296
No errors, just doesn't activate
- Very specific: line 310
Check capitalization: SKILL.md not skill.md
- Distinctive: line 343
Add specific keywords to description
- Distinctive: line 345
Add use case triggers
- Distinctive: line 378
When asked to optimize a skill, follow this workflow:
- Distinctive: line 419
Before marking a skill as validated:
“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.
Files
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-nameValidation 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.mdfile exists (exactly this name, case-sensitive)- YAML frontmatter is present and valid
Common Issues:
| Problem | Solution |
skill.md (lowercase) | Rename to SKILL.md |
| Wrong directory location | Move to .claude/skills/ |
Missing frontmatter --- | Add YAML delimiters |
No name: field | Add required field |
No description: field | Add required field |
Correct Structure:
.claude/skills/my-skill/
├── SKILL.md # Required (exact case!)
├── reference.md # Optional
├── examples/ # Optional
└── templates/ # OptionalStep 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:
| Element | Weight | Example |
| 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:
| Score | Quality | Discovery Likelihood |
| 90-100% | Excellent | Very likely discovered |
| 70-89% | Good | Likely discovered |
| 50-69% | Fair | Sometimes discovered |
| 30-49% | Poor | Rarely discovered |
| 0-29% | Critical | Won't be discovered |
Step 4: Generate Test Phrases
Based on the skill's description, generate phrases to test discovery:
Test Categories:
- Direct Triggers (HIGH confidence)
- Phrases using exact keywords from description
- File type mentions
- Domain-specific terms
- Indirect Triggers (MEDIUM confidence)
- Problem descriptions the skill solves
- Related workflows
- Semantic equivalents
- 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)
- "[Phrase 1]"
- "[Phrase 2]"
- "[Phrase 3]"
Indirect Triggers (MEDIUM confidence)
- "[Phrase 4]"
- "[Phrase 5]"
Should NOT Trigger
- "[Phrase 6]" - Wrong domain
- "[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:
- [Action 1]
- [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 analysisProblems:
- 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 formatsAfter:
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 codeAfter:
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 languageAfter:
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.mdFix:
- Verify path:
.claude/skills/[skill-name]/SKILL.md - Check capitalization:
SKILL.mdnotskill.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 delimiterFix:
---
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:
- Read current SKILL.md
- Analyze description for missing elements
- 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?"
- Generate optimized description with before/after comparison
- 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.mdfile exists (correct capitalization)
YAML Frontmatter
- Starts with
--- - Ends with
--- name:field presentdescription: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
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
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.

