Skill Frontmatter Best Practices

Skill frontmatter is the YAML header that tells Claude when to invoke a skill. The name field identifies the skill. The description field determines whether the skill gets triggered. A bad description means the skill never fires when it should, or fires when it shouldn't.

The principle: the description is a matching function, not a marketing pitch. Its only job is to help Claude decide "should I use this skill for this user request?" Write it for precision matching, not for humans to read.

Frontmatter Structure

Required fields

---
name: cold-outbound-email-writing
description: This skill should be used when the user asks to "write cold outbound", "draft a cold email sequence", "write a sales sequence", "write outbound copy", "build a Lemlist sequence", "build an Outreach sequence", "write B2B cold emails", "draft a 3-email sequence", or any variation of writing outbound email copy for a B2B SaaS audience.
version: 0.1.0
---

Writing the Name

Name rules

• Kebab-case. cold-outbound-email-writing not coldOutboundEmailWriting or cold_outbound_email_writing
• Match the directory. If the skill lives in skills/cold-outbound-email-writing/SKILL.md, the name is cold-outbound-email-writing. No exceptions
• Descriptive, not clever. email-warmup-strategy not warming-up or deliverability-boost. The name should tell you what the skill does without reading the description
• 2-4 words. cold-email-openers is ideal. advanced-enterprise-multi-channel-cadence-design-framework is too long. If you need more than 4 words, the skill scope is too broad. Split it

Name patterns

Writing the Description

The description is the most important field. It determines matching accuracy. A good description triggers on relevant queries and ignores irrelevant ones.

Description structure

This skill should be used when the user asks to
"[trigger 1]", "[trigger 2]", "[trigger 3]",
"[trigger 4]", "[trigger 5]", "[trigger 6]",
"[trigger 7]", "[trigger 8]",
or any variation of [catch-all summary].

Trigger phrase rules

• 6-10 trigger phrases. Fewer than 6 and you miss valid queries. More than 10 and the description gets noisy
• Each trigger is a different phrasing of the same intent. Not 10 different tasks. 10 different ways to ask for the same task
• Include natural language variations. Users say "write cold emails" not "cold outbound email writing." Include the conversational phrasing
• Include tool-specific triggers. If the skill applies to Lemlist, include "build a Lemlist sequence." Users often ask by tool name
• Include problem-phrasing triggers. Not just "write cold emails" but "improve my cold email reply rates." Users sometimes state the problem, not the task
• Include abbreviated and full-form triggers. Both "set up SPF DKIM DMARC" and "configure email authentication for cold outbound"
• Wrap each trigger in double quotes. Consistent formatting helps with matching

Good vs bad trigger phrases

The catch-all phrase

The final phrase ("or any variation of...") is the safety net. It should:

• Summarize the skill's core intent in one phrase
• Include the domain qualifier (e.g., "for B2B SaaS")
• Be specific enough to exclude adjacent skills

Good catch-all:

or any variation of writing outbound email copy
for a B2B SaaS audience

Bad catch-all:

or any variation of email-related tasks

The bad version would match email verification, email warmup, email analytics. Those are different skills.

Avoiding Trigger Collisions

What a collision is

Two skills fire on the same query because their descriptions overlap.

Skill A: cold-outbound-email-writing
  Trigger: "write cold emails"

Skill B: cold-email-personalization
  Trigger: "personalize cold emails"

User query: "write personalized cold emails"
  → Both skills match. Claude picks one. Might be wrong.

Collision prevention rules

• Each skill owns a specific verb. Email writing owns "write", "draft", "compose." Personalization owns "personalize", "customize", "tailor." Don't overlap verbs
• Scope by specificity. A broader skill (cold-outbound-email-writing) handles general requests. A narrower skill (cold-email-subject-lines) handles specific requests. The narrow skill's triggers should be narrow enough that the broad skill doesn't match
• Test for collisions. Before finalizing a description, check 5 other skills in the same category. Would any of their triggers fire on your skill's queries? Would your triggers fire on their queries?
• Use exclusion language in the catch-all when needed. "Any variation of personalizing cold email content (not full sequence writing)" clarifies the boundary

Common collision pairs

Version Management

Versioning rules

Version rules

• Start every new skill at 0.1.0. Not 1.0.0. The 0.x prefix signals "draft, not yet validated"
• Bump to 1.0.0 when the skill passes eval. Run the skill on 10 test queries. If it triggers correctly and produces good output, promote to 1.0
• Never skip versions. 0.1.0 → 0.2.0 → 0.3.0, not 0.1.0 → 0.5.0. The version log should show a clear progression

Formatting Rules

YAML formatting

• Three dashes to open and close. --- on its own line before and after the YAML block
• No trailing spaces. YAML is whitespace-sensitive. Trailing spaces can cause parsing errors
• Description on one line. Even if it's long. Don't break the description across multiple lines with YAML multi-line syntax. One continuous string is more reliable for matching
• No quotes around the name. name: cold-outbound-email-writing not name: "cold-outbound-email-writing"
• Double quotes for the description value. Only if it contains special characters. Otherwise, no quotes needed. But if in doubt, use quotes

Common YAML mistakes

Pre-Publish Checklist

Before publishing a skill's frontmatter:

• [ ] Name is kebab-case and matches the directory name
• [ ] Name is 2-4 words, descriptive
• [ ] Description starts with "This skill should be used when the user asks to"
• [ ] Description contains 6-10 trigger phrases in double quotes
• [ ] Trigger phrases are natural language (how users actually ask)
• [ ] Trigger phrases include tool-specific variations where relevant
• [ ] Trigger phrases include problem-phrasing variations
• [ ] Catch-all phrase includes domain qualifier ("for B2B SaaS")
• [ ] No trigger collisions with skills in the same category (checked 5 adjacent skills)
• [ ] Version is 0.1.0 for drafts, 1.0.0+ for validated skills
• [ ] YAML parses without errors (tested with a YAML validator)

Anti-Pattern Check

• Description is a marketing pitch. "This powerful skill helps teams unlock the potential of cold outbound by leveraging AI-driven personalization." Claude doesn't need to be sold. It needs trigger phrases. Write for matching, not marketing
• Only 2 trigger phrases. The skill fires on "write cold emails" and "draft outbound sequences" but misses "build a Lemlist campaign," "create a cold email," and "write a sales email." Include 6-10 diverse phrasings
• Trigger phrases are all synonyms. "Write cold emails", "compose cold emails", "author cold emails", "craft cold emails." These are the same query phrased 4 ways. Include different angles: tool-specific, problem-phrased, abbreviated
• Catch-all is too broad. "Any variation of email tasks" matches email verification, deliverability, analytics, and writing. Narrow to "any variation of writing outbound email copy for B2B SaaS"
• Name doesn't match directory. name: cold-email-writing but the directory is cold-outbound-email-writing/. The mismatch causes routing failures. Always verify name matches directory exactly
• Never updating the version. The skill has been edited 12 times and is still at version 0.1.0. Bump the version on every meaningful change so you can track which version is deployed
• Description broken across multiple YAML lines. Using > or | for multi-line strings. This can cause matching issues. Keep the description as one continuous string, even if it's long