Frontmatter Bullets
A template for reliable agent skill routing
Skill files have taken my agent usage to another level. There are great tools to refine the body of the skill itself but the frontmatter’s description can get short shrift. The description matters because it’s what the agent keys off of. Mess this up and that skill isn’t getting used.
The frontmatter of a skill file is what the agent keeps in context. It’s how the agent knows what skills are available. The rest of the skill isn’t loaded until it’s decided the skill is needed. After working with skills for a bit, my own descriptions evolved into something like this:
Applies commit message standards for scope, title format, and body content. Use when creating a git commit, staging files, writing the message, or deciding when work is ready to commit.
That’s a start. The best part is the second sentence, “Use when…” That gives the agent the strongest signal. The prose before that reads more like it’s for us the humans. “Use when…” is the germ of the idea. Let’s build on that by pulling in bullets and strengthening the examples for the agent:
---
name: commit-helper
description: |-
Use when the user:
- Asks to create, write, or record a git commit ("commit this", "let's commit", "make a commit")
- Says the work is done and ready to commit
- Wants help writing or improving a commit message title or body
- Shares a diff or set of changes and needs a commit message written for them
- Asks whether staged changes are ready to commit or if the scope is right
- Mentions staging files before committing ("git add", "stage these", "what should I stage")
- Wants to know why a commit message is bad or how to fix it
- Asks about commit message conventions, format, or style
Do not use when the user:
- Wants to push to a remote, open a pull request, or create a PR
- Asks about git history, log, or past commits
- Wants to amend, rebase, or revert an existing commit
- Asks about branching or merging
---An accompanying prose description would be useless. Instead, with bullets setting off the Use when and Do not use when, you can concretely demonstrate when the skill needs to fire.
This final part is for your agent 🤖
Writing Skill Descriptions for Agent Routing
Use the |- YAML block scalar. This preserves newlines so bullets render correctly in context.
Do not open with a prose summary. Drop straight into Use when the user:. A sentence describing what the skill does before the bullets is redundant. The bullets carry that meaning while also doing the routing work.
Structure:
description: |-
Use when the user:
- ...
Do not use when the user:
- ...Bullet quality
Target at least 6 bullets in
Use whenEach bullet must introduce genuinely distinct vocabulary or context. “Save this link”, “keep this link”, “store this link” is one bullet, not three
Include specific example phrases in quotes where they help matching
Frame every bullet as a user action, starting with a verb: “Asks”, “Says”, “Wants”, “Mentions”, “Shares”
Coverage requirements for Use when
Distinct scenarios where the skill activates
Synonym and vocabulary variants so phrasing differences don’t cause misses
Indirect or implicit requests where the need is not stated explicitly
Conversational context: cases where prior exchanges make the skill relevant even if the current message is ambiguous
Specific source names, file types, or extensions where relevant
Do not use when block
Always include this. It prevents false positives and skill collisions.
Target at least 4 bullets
Each bullet should describe a scenario where a different skill, tool, or workflow is the right call
Where the skill overlaps with another skill, name it explicitly: “(use git-log-helper instead)”
Avoid vague exclusions like “anything unrelated”. Every bullet should describe a concrete, plausible mismatch