General: Skill Creation Guidelines

Standard template and conventions for creating skills in .claude/skills/.

When to Create a Skill

Create when:

• Defining reusable patterns or conventions
• Documenting best practices for consistent application
• Establishing naming conventions or code standards

Don't create for:

• One-off tasks or project-specific logic
• Simple documentation that doesn't need enforcement

Skill Structure

Each skill is a single SKILL.md file in its own folder. No supporting files.

Required: YAML Frontmatter

---
name: category-specific-name
description: Use when [clear, actionable trigger]
---

Fields:

• name: Kebab-case {category}-{specific-name} (e.g., frontend-query-hooks, supabase-migrations)
• Categories: frontend-*, supabase-*, general-*
• description: Must start with "Use when" - specific and actionable

# ✅ Good descriptions
description: Use when creating or using TanStack Query hooks for data fetching
description: Use when creating database migrations or modifying schema

# ❌ Bad descriptions
description: Query hooks guidelines  # Not actionable
description: This skill contains...  # Not a trigger

Required: SKILL.md Content

---
name: skill-name
description: Use when...
---

# Title

Brief introduction.

## Core Pattern/Convention

Primary guidelines and rules with code examples.

## Common Mistakes

- ❌ Wrong pattern → ✅ Correct pattern

## Related Skills

- **other-skill** - How it relates

<!-- Last compacted: YYYY-MM-DD -->

Best Practices:

• Start with most important/frequently-used information
• Use code examples liberally (✅ correct and ❌ incorrect)
• Be explicit (MUST, SHOULD, NEVER)
• Keep focused - one cohesive topic per skill
• All content in SKILL.md - no supporting files

Directory Layout

.claude/skills/
├── frontend-query-hooks/
│   └── SKILL.md
├── supabase-migrations/
│   └── SKILL.md
└── general-skill-making/
    └── SKILL.md

One folder, one file. The Skill tool only loads SKILL.md - supporting files are never read.

Naming Conventions

Element	Pattern	Example
Skill name	{category}-{topic}	frontend-query-hooks
Directory	Same as skill name	.claude/skills/frontend-query-hooks/
File	SKILL.md (uppercase)	Always SKILL.md

Creating a New Skill

# 1. Create directory
mkdir -p .claude/skills/frontend-form-validation

# 2. Create SKILL.md with frontmatter + content

Example:

---
name: frontend-form-validation
description: Use when implementing form validation with React Hook Form or custom validators
---

# Frontend: Form Validation

[All content here - no separate files]

<!-- Last compacted: 2026-01-15 -->

Skill Invocation

Skills are loaded via the Skill tool:

Skill("frontend-query-hooks");

The /s command extracts skill names/descriptions:

awk 'FNR<=10 && /^(name|description):/' .claude/skills/*/SKILL.md

Important: Only SKILL.md is loaded. Never create examples.md or reference.md - they won't be read.

Maintenance

• Compact lengthy skills with /compact-skills
• Update related skills when patterns change
• Remove obsolete skills