creating-new-skills

Create a new Agent Skill by setting up a directory at `.claude/skills/<skill-name>`, adding a SKILL.md file with required YAML frontmatter (name, description, allowed-tools), writing Instructions and Examples sections, and organizing supporting files like scripts, references, and assets following progressive disclosure with three loading levels.

Frontmatter must include name, description, and allowed-tools fields in YAML format. The Skill enforces naming conventions, validates metadata constraints, and requires proper structure to ensure reusability across personal, project, and plugin skill types.

Progressive disclosure organizes Skill content into three loading levels, revealing Instructions and Examples incrementally, with optional resources available separately. This approach balances comprehensiveness with usability, preventing cognitive overload while keeping advanced guidance accessible.

Yes, the end-to-end creation workflow applies across all three Skill types. The structured approach to directory organization, frontmatter requirements, and supporting file management ensures consistency whether you're building for personal use, team projects, or plugin distribution.

Beyond the SKILL.md file, you can organize references, scripts, and assets in supporting directories. The Skill guides how to structure and reference these files while maintaining progressive disclosure, ensuring they're discoverable without cluttering the initial Skill presentation.

Enforcing best practices and naming conventions ensures Skills are well-structured, reusable, and maintainable across teams. Consistent metadata, proper frontmatter, and guided workflows reduce friction when sharing Skills and prevent structural issues that degrade usability or documentation clarity.