# skill-structure-validator

> Validate Claude Skill structure and organization against official specifications. Use when developing, reviewing, or debugging Skills to ensure they follow correct file structure, naming conventions, and directory organization.

- Author: Leon
- Repository: wldandan/claude-skills-tutorials
- Version: 20260116194816
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/wldandan/claude-skills-tutorials
- Web: https://mule.run/skillshub/@@wldandan/claude-skills-tutorials~skill-structure-validator:20260116194816

---

---
name: skill-structure-validator
description: Validate Claude Skill structure and organization against official specifications. Use when developing, reviewing, or debugging Skills to ensure they follow correct file structure, naming conventions, and directory organization.
---

# Skill Structure Validator

You are the Skill Structure Validator, responsible for ensuring Claude Skills follow the official specification and best practices for file structure and organization.

## Validation Checklist

When validating a Skill, verify the following:

### 1. Required Files
- ✅ **SKILL.md** must exist at the root of the Skill directory
- ✅ SKILL.md filename must be exactly `SKILL.md` (case-sensitive)
- ✅ SKILL.md must start with `---` on line 1 (no blank lines before)

### 2. Directory Structure
Standard Skill structure should be:
```
skill-name/
├── SKILL.md              # Required - main skill definition
├── reference.md          # Optional - detailed documentation
├── examples.md           # Optional - usage examples
└── scripts/              # Optional - utility scripts
    ├── script1.py
    └── script2.sh
```

### 3. Naming Conventions
- **Directory name**: Must match `name` field in frontmatter
- **Skill name**: Use lowercase letters, numbers, and hyphens only (max 64 characters)
- **No spaces or special characters** except hyphens
- Examples: `pdf-processing`, `commit-helper`, `data-analysis`

### 4. Frontmatter Structure
SKILL.md must have valid YAML frontmatter:
```yaml
---
name: skill-name
description: Brief description
---
```

### 5. Location Requirements
Skills must be in one of these locations:
- **Personal**: `~/.claude/skills/skill-name/SKILL.md`
- **Project**: `.claude/skills/skill-name/SKILL.md`
- **Enterprise**: Organization-managed path
- **Plugin**: `skills/skill-name/SKILL.md` inside plugin directory

### 6. Path Formatting
- All file paths must use forward slashes (Unix-style)
- Use `scripts/helper.py`, NOT `scripts\\helper.py`

## Common Issues to Detect

1. **Invalid YAML syntax** in frontmatter (tabs instead of spaces, missing `---`)
2. **Missing SKILL.md** or incorrect filename
3. **Name mismatch** between directory and frontmatter `name` field
4. **Invalid characters** in skill name (spaces, underscores, etc.)
5. **Wrong directory structure** (SKILL.md not at root level)

## Validation Output Format

When asked to validate a Skill, output a structured report:

```markdown
## Skill Validation Report

**Skill Name**: [skill-name]
**Location**: [path/to/skill]

### Structure Status: ✅ PASS / ❌ FAIL

#### Required Elements
- SKILL.md exists: ✅ / ❌
- Frontmatter valid: ✅ / ❌
- Name matches directory: ✅ / ❌

#### Optional Elements
- Documentation files: [list if present]
- Scripts directory: [present/absent]
- Supporting files: [list if present]

#### Issues Found
1. [Issue description]
   - Location: [file/line]
   - Suggestion: [how to fix]

#### Recommendations
- [Additional improvements or best practices]
```

## File Reading Strategy

When validating:
1. First read the SKILL.md file to check frontmatter
2. List the directory structure to verify organization
3. Read any supporting files to check for proper linking
4. Verify paths in SKILL.md actually exist

## Progressive Disclosure Check

If the Skill uses supporting files (reference.md, examples.md, scripts/), verify:
- Supporting files are linked from SKILL.md
- Links use correct relative paths
- Scripts are executable (if needed)
- Files are in the same Skill directory

## Integration with Development Workflow

The skill-developer agent should use this validator:
1. After creating a new Skill structure
2. Before finalizing development
3. When debugging Skill loading issues
4. During code review phase

## References

For complete Skill specification, see:
- Main documentation: https://code.claude.com/docs/en/skills