Validation

The CLI validates Skills before pushing to ensure they meet requirements. This page covers all validation rules.

Skill Name Requirements

The Skill name (defined in SKILL.md frontmatter) must follow these rules:

Rule	Requirement
Characters	Lowercase letters, numbers, and hyphens
Length	1 to 64 characters
Start/End	Cannot start or end with a hyphen
Reserved	Cannot be `anthropic`, `claude`, `bluebag`

Valid Names

pdf-processing
data-analysis-v2
my-tool-123

Invalid Names

Name	Problem
`PDF-Processing`	Uppercase not allowed
`my_skill`	Underscores not allowed
`-my-skill`	Starts with hyphen
`my-skill-`	Ends with hyphen
`claude`	Reserved name

File Type Requirements

Only specific file types are allowed in Skills:

Documents

Extension	Description
`.md`	Markdown files
`.txt`	Plain text files
`.json`	JSON data files
`.yaml`	YAML configuration
`.yml`	YAML configuration (alternate)
`.xml`	XML documents

Code

Extension	Description
`.js`	JavaScript
`.ts`	TypeScript
`.py`	Python
`.sh`	Shell scripts

Configuration

Extension	Description
`.toml`	TOML configuration
`.ini`	INI configuration
`.env.example`	Environment variable templates

Templates

Extension	Description
`.hbs`	Handlebars templates
`.mustache`	Mustache templates
`.ejs`	EJS templates
`.html`	HTML files

Binary Exceptions

These binary file types are explicitly allowed:

Extension	Description
`.ttf`	TrueType fonts
`.pdf`	PDF documents
`.gz`	Gzip compressed files

Unsupported Types

Most binary executables and other file types are not allowed for security reasons:

Executables: .exe, .dll, .so
Images: .png, .jpg, .gif
Media: .mp3, .mp4
Archives: .zip, .tar (except .gz)
Databases: .db, .sqlite

Talk to us on Discord if you need a file type that isn't currently supported.

File Size Limits

Limit	Maximum
Individual file	10 MB
Total Skill size	100 MB

Talk to us on Discord if large files are required.

Required Files

Every Skill must have a SKILL.md file at its root with valid YAML frontmatter:

---
name: my-skill
description: A description of what this skill does.
---

# My Skill

Instructions...

Required Frontmatter Fields

Field	Required	Description
`name`	Yes	Unique identifier for the Skill
`description`	Yes	What the Skill does and when to use it

Excluded Files

The following are automatically excluded from uploads:

Hidden Files

Files and directories starting with . are ignored:

.git/
.env
.DS_Store
.gitignore

Binary Detection

Non-whitelisted files are checked for binary content. Files containing null bytes are rejected.

Validation Errors

Missing SKILL.md

Missing SKILL.md at /path/to/skill/SKILL.md

Solution: Create a SKILL.md file with valid frontmatter.

Invalid Skill Name

Invalid skill name "My_Skill". Use lowercase letters, numbers, and hyphens.

Solution: Rename using only lowercase letters, numbers, and hyphens.

Missing Description

Missing description in SKILL.md. Provide a description in the frontmatter.

Solution: Add a description field to your YAML frontmatter.

Unsupported Extension

File "image.png" has unsupported extension ".png".

Solution: Remove the file or use an allowed format.

File Too Large

large-file.txt exceeds the 10MB file size limit.

Solution: Reduce file size or host large files externally.

Skill Too Large

Skill exceeds the 100MB total size limit.

Solution: Remove unnecessary files or split into multiple Skills.

Binary File Detected

File "data.bin" appears to be binary. Only text files are allowed.

Solution: Remove the file or use an allowed binary format (.ttf, .pdf, .gz).

On this page