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

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