Test and validate agent skills against the Agent Skills Specification v1.0. Use before deploying skills to ensure spec compliance and catch structural issues.
Validate agent skills against the Agent Skills Specification v1.0 with comprehensive testing and reporting.
Use skill-tester when you need to:
Check available options:
python scripts/test_skill.py --help
Run full validation:
python scripts/test_skill.py /path/to/skill-directory
The validator checks:
✓ PASSED - Requirement met
✓ Directory exists: skill-name
✓ SKILL.md file exists
✓ YAML frontmatter is valid
✓ Required field present: 'name'
✓ Required field present: 'description'
✓ Skill name format is valid: 'skill-name'
✓ Directory name matches YAML name: 'skill-name'
✓ Description explains when to use the skill
✓ SKILL.md body has 1234 words (<5,000)
⚠ WARNINGS - Should be addressed
⚠ Description is 250 chars (recommended ~200)
⚠ SKILL.md body has 5,200 words (recommended <5,000)
⚠ Description should explain WHEN to use the skill
⚠ Possible hardcoded credential detected
✗ FAILED - Must be fixed
✗ SKILL.md file not found (case-sensitive)
✗ Invalid YAML frontmatter: mapping values are not allowed here
✗ Missing required field in YAML: 'description'
✗ Skill name exceeds 64 characters: 72
✗ Skill name must be hyphen-case: 'Skill_Name'
✗ Directory name 'skill-name' does not match YAML name 'skillname'
✗ Description exceeds 1024 characters (1500 chars)
✗ Referenced file does not exist: scripts/missing.py
Errors prevent the skill from working correctly:
Warnings indicate quality issues:
After fixes:
python scripts/test_skill.py /path/to/skill-directory
Verify:
Checks:
Common Issues:
skill.md instead of SKILL.mdChecks:
---name, descriptionCommon Issues:
---Checks:
name field exactlyValid Examples:
code-analyzerapi-doc-generatortest-runnerInvalid Examples:
Code_Analyzer (underscores, capitals)codeAnalyzer (camelCase)code analyzer (spaces)Checks:
Good Description:
description: Analyze code complexity using cyclomatic complexity metrics. Use when assessing code maintainability or identifying refactoring candidates.
Poor Description:
description: This skill helps with code.
Checks:
Common Issues:
Checks:
Security Patterns Checked:
password: "..."api_key: "..."secret: "..."token: "..."Purpose: Main validation script for skill testing
Usage:
python scripts/test_skill.py <skill-directory>
Exit Codes:
0: All checks passed1: One or more checks failedOutput: Formatted validation report with passed, warnings, and failed checks
Purpose: Validate YAML frontmatter only
Usage:
python scripts/validate_yaml.py <skill-directory>
Checks:
Skill Structure:
brand-guidelines/
└── SKILL.md
SKILL.md:
---
name: brand-guidelines
description: Apply brand visual identity guidelines including colors, typography, and spacing. Use when creating branded materials or reviewing designs.
license: MIT
---
# Brand Guidelines
[Content follows...]
Validation Result:
✓ PASSED (9)
✓ Directory exists: brand-guidelines
✓ SKILL.md file exists
✓ YAML frontmatter is valid
✓ Required field present: 'name'
✓ Required field present: 'description'
✓ Skill name format is valid: 'brand-guidelines'
✓ Directory name matches YAML name: 'brand-guidelines'
✓ Description explains when to use the skill
✓ SKILL.md body has 245 words (<5,000)
RESULT: PASSED - Skill is valid
Skill Structure:
Code_Analyzer/
└── SKILL.md
SKILL.md:
---
name: code-analyzer
description: Analyzes code.
---
# Code Analyzer
Run the analysis script from the scripts directory.
Validation Result:
✗ FAILED (2)
✗ Directory name 'Code_Analyzer' does not match YAML name 'code-analyzer'
⚠ WARNINGS (1)
⚠ Description should explain WHEN to use the skill
RESULT: FAILED - Fix errors before using this skill
Fixes Required:
code-analyzerSKILL.md:
---
name: data-processor
description: This skill provides comprehensive data processing capabilities including cleaning, transformation, validation, analysis, and reporting across multiple data formats and sources with support for batch and streaming operations.
---
Validation Result:
✓ PASSED (7)
[... passed checks ...]
⚠ WARNINGS (2)
⚠ Description is 210 chars (recommended ~200)
⚠ Description should explain WHEN to use the skill
RESULT: PASSED with warnings - Consider addressing warnings
Improvements:
description: Process, clean, and transform data across multiple formats. Use when preparing datasets for analysis or integrating data from different sources.
❌ Wrong:
Directory: data-analyzer
YAML: data_analyzer
✓ Correct:
Directory: data-analyzer
YAML: data-analyzer
❌ Wrong:
skill.md
Skill.md
SKILL.MD
✓ Correct:
SKILL.md
❌ Wrong:
description: Helps with testing
✓ Correct:
description: Run Playwright-based web application tests. Use when validating UI functionality or running end-to-end test suites.
❌ Wrong: Reference a script file that doesn't exist in the skill directory.
✓ Correct: Only reference files that are actually bundled with the skill.
Use this before deploying skills:
python scripts/test_skill.py /path/to/skillscripts/test_skill.pyscripts/validate_yaml.py
