What is the maximum length for a Claude Code Skill description?

The description field in the YAML frontmatter must be no longer than 1,024 characters and should use third-person phrasing to describe the skill's utility.

How should I handle complex skills with high word counts?

Use progressive disclosure: keep the main SKILL.md file under 500 lines and move detailed patterns or extended examples into a 'references/' subdirectory.

What subdirectories are allowed within a skill folder?

To maintain a standardized environment, only 'scripts/', 'references/', and 'assets/' subdirectories are permitted within a skill directory.

Why must the directory name match the skill name exactly?

Exact matching between the 'name' field in the frontmatter and the directory layout is required for the Claude Code environment to correctly locate, validate, and invoke the skill.

Can I use underscores in my Claude Skill name?

No, skill names must follow a strict kebab-case pattern (lowercase letters, numbers, and hyphens) and must start with a letter.

Claude Skill Architect

Name: Claude Skill Architect
Author: majesticlabs-dev

bymajesticlabs-dev

•

Developer Tools

Standardizes the creation and validation of Claude Code Skill files to ensure consistent formatting, naming, and metadata.

Skill Structure provides a rigorous framework for developing custom Claude Code Skills, offering definitive guidance on naming conventions, directory layouts, and frontmatter requirements. It ensures that developers follow best practices for progressive disclosure—splitting complex skills into manageable references and scripts—while enforcing strict validation rules for naming patterns and file lengths to maintain a high-quality, interoperable skill ecosystem.

Key Features

01Provides a comprehensive validation checklist for skill integrity and compliance

02Implements progressive disclosure rules for modularizing complex skill documentation

03Defines standard directory layouts for both flat and nested skill structures

04Enforces kebab-case naming conventions and character limits for skill identification

0518 GitHub stars

06Standardizes YAML frontmatter for mandatory metadata and tool access permissions

Use Cases

01Organizing a large library of AI skills into categorized, nested directory structures

02Bootstrapping new custom Claude Code Skills with correct metadata and formatting

03Refactoring monolithic skill files into modular components using references and scripts

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add majesticlabs-dev/majestic-marketplace skill-structure

For use in Claude.ai and ChatGPT

Download Skill