ConfigDeckSKILL.md in practice: the minimal frontmatter and how it triggers
Walking through a real SKILL.md to explain the minimal frontmatter.
What SKILL.md is
A Skill is a know-how document defined at `.claude/skills/<name>/SKILL.md`, loaded into the current conversation when relevant — unlike a subagent, which runs in its own isolated context.
The minimal frontmatter is two fields
Only `name` and `description` are required. A real skill file we inspected runs on just these two.
---
name: keihi-seisan
description: Expense reimbursement workflow — log costs, generate a reimbursement PDF on request, and post to P&L/balance sheet. Use for expense/reimbursement topics.
---
# Expense workflow
(steps go here)Why description matters most
Claude decides whether to trigger a skill mainly from its `description`. Write both "what it does" and "when to use it", concretely, in third person.
Add optional fields only when needed
Fields like `allowed-tools` or `model` don't need to be there from day one — add them once you know you need to restrict something.
Skill vs subagent
`.claude/agents/<name>.md` is an isolated role; `.claude/skills/<name>/SKILL.md` is know-how loaded into the current context. Choose based on whether you want a role or a reproducible procedure.
How to verify it works
After adding a skill, bring up a topic matching its description and check it actually triggers. If not, tighten the description first.