Verify Skill: $1

Overview

You are a skill validation specialist for the Claude Code Developer Kit. Your task is to perform a comprehensive validation of the skill "$1" against all DevKit standards.

Usage

/devkit.verify-skill $ARGUMENTS

Arguments

Execution Instructions

Agent Selection: To execute this task, use the following approach:

• Primary: Use general-purpose agent with appropriate domain expertise
• Or use specialized agent if available for the specific task type

Validation Process

Execute the following checks in sequence:

1. Skill Existence Check

• Search for the skill directory in the following locations (in this order):
  • .claude/skills/$1/ (project-level)
  • ~/.claude/skills/$1/ (user-level)
  • ./skills/**/$1/ (any category subfolder under the repo skills/ directory — recursive search)
  • Any other project-local plugin directories that the repository documents for skills (if present)
• Verify that a SKILL.md file exists inside the found skill directory
• Important: many development workflows (for example when authoring a Claude plugin or a shared skills repo) keep skills under top-level skills/ categories (e.g. skills/langchain4j/<skill-name>). This is an acceptable and supported location for the purposes of validation and MUST NOT be treated as a false-positive or as a failure just because .claude/skills/ or ~/.claude/skills/ do not contain the skill.
• If the skill cannot be found in any of the locations above, report failure (Existence).

2. Requirements Conformance (@.docs/skills.md)

Check that the skill complies with all requirements from the official Skills documentation:

SKILL.md Frontmatter:

• name field: lowercase letters, numbers, hyphens only (max 64 characters)
• description field: present and descriptive (max 1024 characters). Description includes BOTH what the skill does AND when to use it
• allowed-tools field: uses valid tool names only
• category: field, valid category
• tags: field, relevant, and descriptive (no generic tags like "skill" or "devkit")
• version field: uses semantic versioning (e.g., 1.0.0) Important: Other frontmatter fields are not allowed.

File Structure:

• SKILL.md uses valid YAML frontmatter (opening and closing ---)
• No YAML syntax errors (tabs, incorrect indentation)
• All referenced files in SKILL.md exist in the skill directory
• File paths use forward slashes (Unix style), not backslashes

Content Quality:

• Description is specific with trigger keywords (not vague/generic)
• Skill has a clear "When to Use" or "Instructions" section
• Examples are present and demonstrate the skill
• Examples (examples.md) file exists if multiple examples are provided
• Supporting files (if any) are properly referenced with Markdown links
• References (reference.md) file exists if the skill is complex

3. Template Adherence (@.docs/skill_template.md)

Verify the skill structure matches the template:

Required Sections:

• Skill name as H1 heading
• "When to Use This Skill" section with clear use cases
• "Core Concepts" or "Instructions" section
• "Examples" or practical demonstrations
• "Best Practices" or "Summary" section

Metadata Alignment:

• Frontmatter includes recommended fields (name, description, category, tags, version)
• Version number is present and follows semantic versioning (if included)
• Tags are relevant and descriptive (if included)
• Category is specified (if included)

Content Organization:

• Logical section hierarchy
• Progressive complexity in examples
• Clear cross-references to related content
• Proper code formatting and syntax highlighting

4. Dependency Validation (Context7 or u2m)

IMPORTANT: Only perform this check if the skill references specific libraries or frameworks.

For each library/framework mentioned in the skill:

• Identify the library name and version (if specified)
• Use mcp Context7 to check if the library is current
• Verify trust score is adequate (≥ 7.0 for enterprise skills)
• Check if there are newer stable versions available
• Note if documentation indicates breaking changes If context7 is not accessible, use this bash tool u2m.
• Verify with bash tool u2m -v <link-reference> to get the latest version and trust score
• Clean every output from u2m to extract only relevant data IF u2m fails, note this but do not fail validation Finally, compare the current version with the latest stable version found.

Skip this check if:

• The skill is language-agnostic or doesn't reference specific libraries
• The skill only uses built-in language features
• No version numbers are specified

Output Format

Success Case

If ALL checks pass, output:

✅ Validation completed: The skill '$1' complies with all standards.

Details:
- ✅ SKILL.md file present and valid
- ✅ Frontmatter correct (name, description)
- ✅ Structure conforms to the template
- ✅ All referenced files exist
- ✅ [Dependencies validated / No dependencies to validate]

Failure Case

If ANY check fails, output:

❌ Validation failed for the skill '$1'.

Required actions:

* **[Category]:** [Specific description of the issue]
* **[Category]:** [Specific description of the issue]
...

Categories for errors:

• Existence: Skill or SKILL.md not found
• Requirements: YAML frontmatter errors, invalid field values, missing required fields
• Template: Missing sections, incorrect structure, poor organization
• File: Referenced files not found, incorrect path format
• Dependencies: Outdated libraries, low trust scores, breaking changes
• Content: Vague descriptions, missing examples, poor documentation

Examples of Specific Feedback

Good specific feedback:

• ❌ Requirements: The name field contains uppercase characters. It must use only lowercase letters, numbers, and hyphens.
• ❌ Template: The "When to Use This Skill" section required by the template is missing.
• ❌ File: The reference.md file is referenced in SKILL.md but does not exist in the skill directory.
• ❌ Dependencies: The 'spring-boot' library uses version 2.7.x. Recommended version: 3.2.x (Context7 Trust Score: 9.2).
• ❌ Content: The description does not specify WHEN to use the skill; it only describes what it does.

Bad vague feedback (avoid):

• ❌ The file is not valid
• ❌ There are issues with the template
• ❌ The dependencies might be outdated

Validation Rules

1. Be thorough: Check every requirement systematically
2. Be specific: Each error must include the exact issue and how to fix it
3. Be actionable: Suggest concrete solutions, not just identify problems
4. Be accurate: Only report actual issues found, don't assume
5. Prioritize: List critical issues (existence, syntax errors) before style issues

Additional Notes

• If the skill directory exists but is empty, report as missing SKILL.md
• If YAML frontmatter is malformed, report the specific YAML error
• If Context7 lookup fails, note this but don't fail validation
• Check both .claude/skills/$1/ (project) and ~/.claude/skills/$1/ (personal)
• For multi-file skills, validate that supporting files add value

Begin validation now for skill: $1

Examples

/devkit.verify-skill skill-name