Why Did My Skill Upload Fail?

Last updated: March 21, 2026

Skill uploads can fail for two reasons: the file itself doesn't meet the upload requirements (wrong format, too large, missing SKILL.md), or the skill's name or description breaks the naming rules. This article covers every validation check and the exact error you'll see for each one.

Skill Naming Rules

Skill names are validated when you create a skill through any method — uploading files, writing instructions manually, or having the agent create one. The rules are:

Rule

Error if Violated

Lowercase letters, digits, and hyphens only (a-z, 0-9, -)

Name 'My_Skill' must be hyphen-case (lowercase letters, digits, hyphens only)

Cannot start or end with a hyphen

Name '-my-skill' cannot start/end with hyphen or contain consecutive hyphens

No consecutive hyphens (--)

Name 'my--skill' cannot start/end with hyphen or contain consecutive hyphens

Maximum 64 characters

Name too long (72 chars). Max 64.

Name is required (cannot be empty)

Name is required

Valid names

email-outreach-playbook, weekly-sales-summary, crm-logging, data-cleanup-v2

Invalid names

My_Skill (underscore), Email Playbook (spaces), mySkill (uppercase), -my-skill (starts with hyphen), my--skill (consecutive hyphens)

Description Rules

Rule

Error if Violated

Description is required (cannot be empty)

Description is required

No angle brackets (< or >)

Description cannot contain angle brackets

Maximum 1,024 characters

Description too long (1200 chars). Max 1024.

File Upload Validation (for .zip and .skill archives)

When you upload a .zip or .md file, the platform runs these checks in order. The upload fails at the first check that doesn't pass.

Check

Limit

Error message

Valid zip archive

—

Invalid or corrupt archive

File count

100 files max

Archive contains too many files (max 100)

No unsafe paths (absolute paths, ../ traversal, null bytes)

—

Unsafe file path in archive

Individual file size

10 MB per file

File too large in archive

Compression ratio

100:1 max (zip bomb defense)

Suspicious compression ratio detected

Total decompressed size

50 MB total

Archive total size exceeds limit

Contains a SKILL.md file

—

invalid_skill_md

SKILL.md has valid YAML frontmatter with name and description

—

invalid_skill_md

Supported Upload Formats

  • .md — treated as the SKILL.md file regardless of its original filename

  • .zip — extracted with all the security checks above

  • Other files — stored with their original filename alongside the SKILL.md

What "invalid_skill_md" Means

This error appears when the SKILL.md file is missing or its frontmatter is malformed.

Specifically:

  • The archive doesn't contain a file named SKILL.md

  • The SKILL.md doesn't start with valid YAML frontmatter (the --- delimited block at the top)

  • The frontmatter is missing the required name field

  • The frontmatter is missing the required description field

  • The name or description fails the validation rules listed above

Correct SKILL.md format

---
name: my-skill-name
description: A clear description of what this skill does and when to use it.
---

## Instructions
Your skill instructions go here...

Name Conflicts (Duplicate Names)

If you create a skill with a name that already exists in your workspace, the system automatically appends a number to make it unique — for example, my-skill becomes my-skill-2. This happens silently; you won't see an error, but the skill may have a different name than you expected. Check the skill's name in the Skills page after creation.

Related Docs

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.