validate-skill
Scannednpx machina-cli add skill plaited/development-skills/validate-skill --openclawFiles (1)
SKILL.md
2.5 KB
Validate Skill
Purpose
This skill validates skill directories against the AgentSkills specification. Use it to ensure your skills have proper frontmatter, required fields, and follow naming conventions.
Use when:
- Creating new skills in any agent's skills directory (
.claude/skills/,.cursor/skills/, etc.) - Reviewing PRs that modify skills
- Validating skill structure before publishing
Scripts
validate-skill.ts
Validate one or more skill directories.
bunx @plaited/development-skills validate-skill [paths...]
Arguments:
paths: Paths to validate (defaults to current agent's skills directory)
Options:
--json: Output results as JSON
Examples:
# Validate skills in current directory's .claude/skills/
bunx @plaited/development-skills validate-skill .claude/skills
# Validate Cursor skills
bunx @plaited/development-skills validate-skill .cursor/skills
# Validate a specific skill
bunx @plaited/development-skills validate-skill .claude/skills/typescript-lsp
# Validate multiple paths with JSON output
bunx @plaited/development-skills validate-skill .claude/skills .cursor/skills --json
Validation Rules
Required Fields
name: Skill name (lowercase, alphanumeric with hyphens)description: Brief description of the skill
Naming Conventions
- Name must be lowercase
- Only alphanumeric characters and hyphens allowed
- Cannot start or end with hyphen
- Cannot contain consecutive hyphens
- Maximum 64 characters
- Directory name must match skill name
Optional Fields
license: License identifiercompatibility: Runtime requirementsallowed-tools: Comma-separated list of allowed toolsmetadata: Key-value pairs for additional metadata
Output Format
Human-Readable (default)
ā .claude/skills/typescript-lsp
ā .cursor/skills/my-skill
ā .claude/skills/invalid-skill
ERROR: Missing required field in frontmatter: 'description'
2/3 skills valid
JSON (--json)
[
{
"valid": true,
"path": ".cursor/skills/my-skill",
"errors": [],
"warnings": [],
"properties": {
"name": "my-skill",
"description": "..."
}
}
]
Related Skills
- typescript-lsp - Example of a well-structured skill with scripts
- code-documentation - TSDoc standards for TypeScript/JavaScript code
Source
git clone https://github.com/plaited/development-skills/blob/main/skills/validate-skill/SKILL.mdView on GitHub Overview
Validates skill directories against the AgentSkills specification. It checks for required frontmatter fields, enforces naming conventions, and ensures optional metadata is present when provided. This helps maintain a consistent, publish-ready skills catalog during creation, review, and deployment.
How This Skill Works
The validate-skill.ts script is run via bunx to examine one or more skill directories (defaulting to the current agent's skills directory). It enforces required fields (like name and description), applies naming rules, and reports results in human-readable form or JSON when --json is used.
When to Use It
- Creating a new skill in any agent's skills directory (.claude/skills, .cursor/skills, etc.)
- Reviewing pull requests that modify skills to catch spec violations
- Validating skill structure before publishing to ensure compliance
- Auditing existing skills for naming or frontmatter issues
- Validating multiple skills at once, optionally with JSON output
Quick Start
- Step 1: Choose one or more skill paths to validate (e.g., .claude/skills, .cursor/skills).
- Step 2: Run bunx @plaited/development-skills validate-skill [paths...] with or without --json.
- Step 3: Review the output, fix any errors, and re-run until all skills are valid.
Best Practices
- Provide full path(s) to ensure precise validation (e.g., .claude/skills/typescript-lsp).
- Ensure the required fields name and description are present in the frontmatter.
- Follow naming conventions: lowercase, alphanumeric with hyphens, no leading/trailing or consecutive hyphens, max 64 characters.
- Verify the directory name exactly matches the skill name.
- Use the --json option for machine-readable results and integrate into CI checks.
Example Use Cases
- Validate skills in the current project: bunx @plaited/development-skills validate-skill .claude/skills
- Validate Cursor skills: bunx @plaited/development-skills validate-skill .cursor/skills
- Validate a specific skill: bunx @plaited/development-skills validate-skill .claude/skills/typescript-lsp
- Validate multiple paths with JSON output: bunx @plaited/development-skills validate-skill .claude/skills .cursor/skills --json
- In CI to enforce skill structure before merge
Frequently Asked Questions
Add this skill to your agents
