Creating Claude Code Skills

Claude Code skills use YAML frontmatter at the top of SKILL.md to define metadata. Include required fields: name (in gerund form), description (within length limits), and allowed-tools. This structure makes skills discoverable and reusable across personal, project, and company scopes.

Skill scope determines where it's stored and who can access it. Personal skills are individual-only; project skills are shared within a specific project; company skills are organization-wide. Choose based on reuse needs and audience.

Start with SKILL.md containing frontmatter and core logic. Add optional companion files—REFERENCE.md for detailed documentation, ENVIRONMENTS.md for setup, TROUBLESHOOTING.md for common issues—as your skill grows in complexity.

Use lowercase, hyphen-separated names that describe the task (e.g., parse-json-logs, generate-reports). The name field in frontmatter should use gerund form (verb-ing) to clearly indicate the action the skill performs.

Create a skill when the task is reusable across multiple projects or contexts, benefits from version control, or requires shared documentation. Skills enforce consistent structure and make reasoning transferable; use them for generalizable workflows.

Required frontmatter fields are name (gerund form), description (concise overview), and allowed-tools (list of permitted tools). These fields enable skill discovery, set boundaries, and ensure compatibility across deployment scopes.