building-claude-code-skills

Design, document, and validate Claude Code Skills with SKILL.md structure.

1|Updated Jun 19, 2026

Search Tags:#documentation #best-practices #claude-code #progressive-disclosure #skill-building #cli-patterns

Ready to run

npx skills add https://github.com/gannonh/kata-agents --skill building-claude-code-skills

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: building-claude-code-skills
Source: https://github.com/gannonh/kata-agents/tree/main/skills/building-claude-code-skills
Command: npx skills add https://github.com/gannonh/kata-agents --skill building-claude-code-skills

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill guides teams to design, document, and validate Claude Code Skills with a consistent, production-ready structure.

Core Features & Use Cases

Structured Skill Design: Define name, description, frontmatter, and progressive-disclosure layout.
Editing & Conversion Guidance: Provide patterns for updating SKILL.md, converting sub-agents, and upgrading slash commands to skills.
Project- and Global-Scale Strategy: Apply across single projects or global skill repositories to ensure uniformity.

Quick Start

To start, create a new skill directory named after the gerund-form descriptor, add a SKILL.md with YAML frontmatter, and place any reference and script files in clearly named subdirectories. Then follow the outlined steps to validate metadata and test invocation against sample queries.

Frequently Asked Questions about building-claude-code-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I structure a Claude Code Skill for reliable automatic invocation?▼

To structure a Claude Code Skill for reliable invocation, define a clear name, description, and YAML frontmatter in a SKILL.md file, using a gerund-form directory name and progressive-disclosure layout for reference files.

What is progressive disclosure in Claude Code Skill design?▼

Progressive disclosure in Claude Code Skill design is the practice of organizing reference files and scripts in clearly named subdirectories, keeping the main SKILL.md concise while enabling detailed contextual loading when needed.

How do I validate Claude Code Skill metadata before deployment?▼

You validate Claude Code Skill metadata by checking frontmatter correctness, ensuring intention-revealing file naming conventions, and testing the skill's automatic invocation against sample queries across your project.

Can I apply Claude Code Skill patterns across both single projects and global repositories?▼

Yes, you can apply Claude Code Skill patterns across single projects and global skill repositories to ensure uniform structure, enforcing consistent frontmatter and file organization for reliable automatic invocation.

What are the limitations of managing Claude Code Skills without a consistent structure?▼

Managing Claude Code Skills without a consistent structure leads to frontmatter errors, disorganized reference files, and unreliable automatic invocation, making skill validation and maintenance significantly harder across projects.