Creating a New Skill

Follow these steps when creating a new skill, whether proposed during /done or requested directly.

1. Confirm Scope

Before creating, verify the pattern actually warrants a skill (not just a CLAUDE.md entry):

• Too detailed for CLAUDE.md — needs code examples, decision trees, or multi-section docs
• Reusable across sessions — will be needed repeatedly
• Complex enough to get wrong — without it, Claude might make mistakes or ask the same questions each session

If it's a simple one-liner convention, put it in the project CLAUDE.md instead.

2. Determine Level

Ask the user if not already decided:

• Project-level ({project}/.claude/skills/{name}/SKILL.md) — Specific to one project. Examples: gene naming conventions, project-specific data formats, project-specific workflows.
• User-level (~/.claude/skills/{name}/SKILL.md) — Applies across multiple projects. Examples: plotting conventions, environment management, export formats.

3. Write an Effective Description

The description field in YAML frontmatter is the single most important part of a skill — it determines whether the skill gets activated. Follow these rules:

Front-load trigger conditions

The first sentence should say WHEN to use the skill, not just WHAT it does.

# BAD — describes what, not when:
description: R ggplot2 plotting conventions and theme.

# GOOD — front-loads triggers:
description: R ggplot2 plotting conventions and theme. Use when creating, modifying, or styling ggplot2 plots in R, or when adjusting plot themes, colors, labels, or formatting.

List concrete triggers

Be specific about what actions or contexts should activate the skill. Use verbs: "creating", "modifying", "saving", "debugging", "exporting".

# BAD — too vague:
description: Use when working with files.

# GOOD — specific actions:
description: Use when overwriting existing files, deleting files, or writing to directories that contain important data (data/, outs/).

Add explicit exclusions when needed

If the skill could be confused with similar skills, add "Do NOT load for" clauses.

description: >
  Quarto document conventions for data science analysis scripts (.qmd).
  Use when creating or rendering .qmd analysis scripts in data science projects.
  Do NOT load for Quarto books, websites, or documentation projects.

Cover edge cases in triggers

Think about variations of the task that should also trigger the skill:

Keep it scannable

The description should be 1-3 sentences. If it needs more, use the multi-line > YAML syntax. Put the most important trigger first.

4. YAML Frontmatter Template

---
name: skill-name
description: >
  One-sentence summary of what the skill covers.
  Use when [specific trigger 1], [specific trigger 2], or [specific trigger 3].
  Do NOT load for [exclusion 1] or [exclusion 2].
user-invocable: false
---

Fields:

• name — kebab-case, matches the directory name
• description — trigger-focused (see rules above)
• user-invocable — true only if the user triggers it with /name (like /done, /publish). Most skills are false (auto-loaded based on context).

5. Skill Content Structure

After the frontmatter, organize the skill body:

1. Title — # Skill Name
2. Context/purpose — 1-2 sentences on why this skill exists
3. Rules/conventions — The actual content, organized with ## sections
4. Code examples — When patterns need to be shown, include both R and Python if applicable
5. Common mistakes — What goes wrong without this skill (helps justify its existence)

Keep it focused. A skill should cover one coherent topic, not be a grab-bag.

6. File Workflow

1. Create/edit in ~/.claude/skills/{name}/SKILL.md
2. Use generic paths (e.g., ~/miniconda3, not /Users/username/miniconda3) so skills are portable across machines

7. Register in User CLAUDE.md

After creating a new user-level skill, add it to the appropriate table in ~/.claude/CLAUDE.md under "Available Skills":

• General skills table — if it applies to all project types
• Data Science skills table — if it only applies to data science projects

Project-level skills don't need registration in the user CLAUDE.md — they're discovered automatically from the project's .claude/skills/ directory.