Writing Your First Skill: How to Write description's Trigger Words, How to Layer the Structure, How to Install It Into a Client

Today's Goals

1. Narrow a repeated task down to a skill's boundary, and state what it should not handle
2. Write a usable description following three rules — imperative mood, user intent, and a clear boundary
3. Install a skill into a client's project-level or user-level directory, and confirm it is actually triggered

Yesterday you took three existing skills apart and saw what good looks like. Today you write one of your own. Today's success has a single criterion: you say something natural and it opens up by itself. Once you have read the walkthrough and finished the lab, scroll back to the top and tick off the three goals.

Plain-Language Walkthrough

Choosing a subject: start with the thing you explained three times this week

The work instructions in that filing cabinet were not written out of thin air; a long-tenured employee wrote them after being asked one time too many. Your first skill should come the same way.

The best signal for a subject is "you have already corrected it." You have the AI write a commit message and it writes update code; you say no, our format is a type, a colon, and a description; it fixes it; a different repository, a different session, and it is back to update code. That round trip happened three times this week — those three corrections are the entire content of this skill, and you do not have to invent anything.

The official best practices page puts this bluntly: a skill generated out of the model's own general knowledge comes out full of correct-and-useless lines like "handle errors appropriately" and "follow authentication best practices." A genuinely valuable skill comes from specific experience — your project's conventions, the edges you hit, every sentence you corrected in conversation. So look in these three places when choosing a subject:

First, what you have corrected repeatedly. That is the most direct source, and the content of the correction goes in verbatim.

Second, what is already written in a document nobody reads. The team's commit convention, endpoint agreements, how a report is filled in. They usually sit in a document nobody opens, and as a skill the model comes to consult them rather than a person having to go find them.

Third, what you can read off the commit history. Which changes recur in the same form, which review comments come up again and again. Material like that is dense, because it records what was actually changed rather than what was meant to be done.

Once chosen, immediately do one thing: write down what it does not handle. A write-a-commit-message skill does not care whether the code is correct, whether this should be committed at all, or what the branch should be called. Write that boundary down now, because it goes verbatim into the end of the description shortly. It is the step beginners most often skip and most often pay for — on day three, when we get to anti-patterns, you will see that trying to cover everything is the most common of the four.

The description is the only trigger surface

Now write today's most important line. Recall yesterday's three stages: at session start, the model can see only the name and the description. However beautiful the body, if this one line fails to make the model recognize "time to open me," the whole skill might as well not exist.

The spec gives four authoring principles; here is each one applied:

First, use the imperative mood and write instructions to the model. Write "use when the user is committing code," not "this skill can help generate commit messages." What the model is doing is making a decision — use it or not — so tell it directly when to use it. A self-introducing "This skill does…" sentence contributes nothing to that decision.

Second, write user intent, not internal implementation. What the model matches against is the sentence the user just said, not your implementation details. "Parses and generates per the Conventional Commits spec" is implementation; "use when the user is committing code, writing a commit message, or asking how to describe a change" is intent.

Third, err toward being pushy. The official wording is exactly "err on the side of being pushy": list the applicable situations explicitly, including phrasings where the user never names the domain directly. A user rarely says "write me a commit message per the convention"; they are likelier to say "I'm ready to commit these changes." Put colloquial phrasings like that in too.

Fourth, keep it short. A few sentences to a short paragraph is enough. The limit is 1,024 characters, but this one line is paid on every session — as computed yesterday, twenty skills all written to the limit cost eight thousand tokens for the catalog alone.

On top of those four, add one you derived yourself in yesterday's lab: append a boundary sentence. The first half governs when it appears, and that closing half governs when it stays quiet.

Put all five together and a commit-message skill's description looks like this:

---
name: commit-message
description: Write Git commit messages to the team's convention. Use when the user is committing code, writing a commit message, tidying up staged changes, or asking how this change should be described, even when they never mention conventions or formatting. Only produces the commit message text; does not decide whether to commit and does not run git commands.
---

Section by section: the first sentence is what it does (imperative, short); the long middle is when to use it, with four phrasings spread from formal to colloquial, and that closing "even when they never mention conventions or formatting" is the official "be pushy"; and the end is the boundary, where two "does not" clauses keep the most collision-prone neighboring capabilities out.

Layering the body: steps, examples, pitfalls

The description decides whether it gets opened, and the body decides whether opening it helped. The spec recommends three sections: step-by-step instructions, input and output examples, and common edge cases. In practice, expand them in this order:

Write the workflow as numbered steps. For a task where steps depend on each other and order matters, the numbering is itself a constraint. Every step must be an action that can be completed; do not write sentences with no landing point, like "handle the various situations appropriately."

Give a template for the output format rather than describing it in prose. The spec stresses this one: a model pattern-matching against a concrete structure is far more reliable than reading a paragraph saying "the output should contain a title, key points, and recommendations." A short template goes in the body; a long one, or one used only in specific cases, goes in assets/.

Pitfalls get their own section, and it must stay in the body. The spec calls this section gotchas and notes that it is often the highest-value part of the whole skill — because it holds the facts a reasonable guess would get wrong. "This table uses soft deletes, so every query must include the not-deleted condition" is a pitfall; "watch out for exceptions" is not a pitfall, it is filler. The criterion for a pitfall is one sentence: without this line, would the model get it wrong? If not, delete it.

Why can pitfalls not move into references/? Because the model has to know a pitfall exists before it will go look one up. Putting them in a reference file requires the model to predict it is about to hit something before it hits it, which does not work.

One principle runs throughout: write only what the model does not know. Do not explain what Git is or what a commit is; jump straight to "we have exactly six types here and not one more." The criterion is one question to yourself: without this line, would the model get it wrong? If not it is filler, so delete it and make room for something else.

Installing it into a client

A finished skill counts as installed only once it sits somewhere the client scans. Placement has two dimensions: scope (this project or all projects) and directory convention (the cross-client one or a particular vendor's own).

project root/
├── .agents/skills/commit-message/SKILL.md   # project level, cross-client convention
└── .claude/skills/commit-message/SKILL.md   # project level, Claude Code's own
 
~/
├── .agents/skills/commit-message/SKILL.md   # user level, cross-client convention
└── .claude/skills/commit-message/SKILL.md   # user level, Claude Code's own

.agents/skills/ is the cross-client convention the community settled on, and a skill placed there can be seen by several clients at once; a vendor's own directory (Claude Code's being .claude/skills/) is its native location. The spec itself does not dictate where skill directories go; it defines only what a folder looks like inside — which is why both sets of paths exist. Put a skill in .agents/skills/ to share it across tools, and in a vendor's own directory to give it to one.

Choosing the scope is easy to judge: what holds only for this repository goes project level and travels with the repository, so everyone on the team has it as soon as they pull; cross-project personal habits go user level.

On precedence when two skills collide, there is a divergence you must verify yourself. The prevailing cross-client convention is project level beats user level — closer to the code at hand is more specific and ought to win. But a particular client may have its own hierarchy; Claude Code's documentation, for example, orders enterprise, personal, and project from high to low, so personal beats project, and that reasoning also holds: you would not want a skill arriving from a repository to override the same-named skill you configured yourself. Both designs are reasonable, so check which one your client uses before installing rather than going on instinct. On a collision a client usually logs a warning that a skill was shadowed, and that log line is the first place to look when diagnosing this.

What to do when it does not trigger the first time

You wrote and installed it, said "help me commit these changes," and nothing happened. Check these three things, which cover the overwhelming majority of cases:

First, it was never scanned at all. Confirm whether the client recognizes this directory, whether the SKILL.md filename has the wrong case, and whether name equals the parent directory name. Most clients have a command listing available skills, and absence from that list means it was not scanned, which has nothing whatsoever to do with the description. Always do this step first — get the order wrong and you will spend an afternoon editing a completely innocent description.

Second, frontmatter parsing failed. The most common variant is a bare colon in the YAML: description: use when the user says: help me commit, where that middle colon makes the YAML parser treat the line as invalid. Some clients repair it as a fallback and some skip the skill outright. To use a colon in the description, wrap the whole value in quotes.

Third, the description does not cover the phrasing you used. That is the case that genuinely calls for editing the description. The criterion: can the keywords of the sentence you actually said be matched against something in the description? If not, add them — but add the class of phrasing rather than that one sentence. Copying your exact words in verbatim walks straight into overfitting, and day three is devoted to avoiding that.

There is one more situation that is not a failure and is worth knowing: the task was too easy and the model reckoned it could handle it. The spec states plainly that clients usually consult skills only when a task exceeds the model's own capability. "Read this file for me" will trigger no skill at all, however well the description matches.

The code below turns the first two checks into a script: validating name against its five rules, the length of description, and whether the frontmatter parses. Run it before installing and it saves most of the diagnosis time.

import { readFile } from 'node:fs/promises'
import { basename, dirname } from 'node:path'
 
const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/ // covers both no leading/trailing hyphen and no consecutive hyphens
 
export async function validateSkill(skillMdPath: string): Promise<string[]> {
  const raw = await readFile(skillMdPath, 'utf8')
  const errors: string[] = []
 
  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)
  if (!m) return ['no frontmatter found; the first lines must be --- and the fields']
  const front = m[1]
 
  const name = /^name:\s*(.+)$/m.exec(front)?.[1]?.trim()
  const description = /^description:\s*(.+)$/m.exec(front)?.[1]?.trim()
 
  if (!name) errors.push('missing the required field name')
  else {
    if (name.length > 64) errors.push(`name exceeds 64 characters (currently ${name.length})`)
    if (!NAME_RE.test(name))
      errors.push('name allows only lowercase letters, digits, and single hyphens, and cannot start or end with one')
    const dir = basename(dirname(skillMdPath))
    if (name !== dir) errors.push(`name disagrees with the parent directory: ${name} versus ${dir}`)
  }
 
  if (!description) errors.push('missing the required field description; without it the skill can never be triggered')
  else if (description.length > 1024)
    errors.push(`description exceeds 1024 characters (currently ${description.length})`)
  // A bare colon is the most common YAML trap: a colon in an unquoted value, which many parsers reject outright
  else if (/:/.test(description) && !/^["']/.test(description))
    errors.push('description contains a colon but is not quoted; some clients will fail to parse it')
 
  return errors
}

import re
from pathlib import Path
 
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")  # covers no leading/trailing hyphen and no consecutive hyphens
 
 
def validate_skill(skill_md: Path) -> list[str]:
    raw = skill_md.read_text(encoding="utf-8")
    errors: list[str] = []
 
    m = re.match(r"^---\r?\n(.*?)\r?\n---", raw, re.S)
    if not m:
        return ["no frontmatter found; the first lines must be --- and the fields"]
    front = m.group(1)
 
    name_m = re.search(r"^name:\s*(.+)$", front, re.M)
    desc_m = re.search(r"^description:\s*(.+)$", front, re.M)
    name = name_m.group(1).strip() if name_m else None
    description = desc_m.group(1).strip() if desc_m else None
 
    if not name:
        errors.append("missing the required field name")
    else:
        if len(name) > 64:
            errors.append(f"name exceeds 64 characters (currently {len(name)})")
        if not NAME_RE.match(name):
            errors.append(
                "name allows only lowercase letters, digits, and single hyphens, "
                "and cannot start or end with one"
            )
        if name != skill_md.parent.name:
            errors.append(f"name disagrees with the parent directory: {name} versus {skill_md.parent.name}")
 
    if not description:
        errors.append("missing the required field description; without it the skill can never be triggered")
    elif len(description) > 1024:
        errors.append(f"description exceeds 1024 characters (currently {len(description)})")
    # A bare colon is the most common YAML trap: a colon in an unquoted value, which many parsers reject
    elif ":" in description and not description.startswith(('"', "'")):
        errors.append("description contains a colon but is not quoted; some clients will fail to parse it")
 
    return errors

Budget awareness: two lines

Finally, pin down two numeric lines that run through the remaining five days of this course.

Line one: 500 lines and 5,000 tokens for the body. That is the spec's recommended ceiling, and anything beyond should move into references/. When moving, remember yesterday's rule: state under what condition each file is read, or the content you moved out is effectively lost.

Line two: 1,024 characters for the description. That is a hard limit, but the number to actually watch is not this one — it is all your skills' descriptions added together. Twenty of them written to the limit make eight thousand tokens for the catalog alone, and those eight thousand are paid every turn.

The two lines differ in nature, so do not conflate them: 500 lines is money paid only on a match, and 1,024 characters is money paid continuously. So a body can be written at leisure while a description must be counted to the word.

A practical habit is to watch the total description cost as a metric. The code below totals the description lengths of every skill in a directory and warns when over budget — put it in your own check script alongside yesterday's catalog cost estimator.

import { readdir, readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
const BUDGET_CHARS = 4000 // budget for all descriptions combined; at 4 characters per token, about 1000 tokens
 
export async function checkBudget(skillsDir: string): Promise<boolean> {
  const dirs = (await readdir(skillsDir, { withFileTypes: true })).filter((e) => e.isDirectory())
  let total = 0
  for (const d of dirs) {
    const raw = await readFile(join(skillsDir, d.name, 'SKILL.md'), 'utf8').catch(() => '')
    const desc = /^description:\s*(.+)$/m.exec(raw)?.[1]?.trim() ?? ''
    total += desc.length
    if (desc.length > 300)
      console.warn(`${d.name} has a ${desc.length}-character description; consider trimming under 300`)
  }
  console.log(`${dirs.length} skills' descriptions total ${total} characters, budget ${BUDGET_CHARS}`)
  return total <= BUDGET_CHARS
}

import re
from pathlib import Path
 
BUDGET_CHARS = 4000  # budget for all descriptions combined; at 4 characters per token, about 1000 tokens
 
 
def check_budget(skills_dir: Path) -> bool:
    dirs = sorted(p for p in skills_dir.iterdir() if p.is_dir())
    total = 0
    for d in dirs:
        skill_md = d / "SKILL.md"
        raw = skill_md.read_text(encoding="utf-8") if skill_md.exists() else ""
        m = re.search(r"^description:\s*(.+)$", raw, re.M)
        desc = m.group(1).strip() if m else ""
        total += len(desc)
        if len(desc) > 300:
            print(f"warning: {d.name} has a {len(desc)}-character description; consider trimming under 300")
    print(f"{len(dirs)} skills' descriptions total {total} characters, budget {BUDGET_CHARS}")
    return total <= BUDGET_CHARS

Source Reading

Hands-On Lab

There is code today, but the code is not the deliverable — the deliverable is a skill triggered by one natural sentence. Before starting, find your team's commit convention and keep it beside you; with no written convention, pull the last twenty commits and see what they actually look like. When stuck, go back to the section on what to do when it does not trigger and check in order without skipping steps.

1. Open the solution's SKILL.md, look only at the frontmatter and guess when it would be triggered, then read the body to check whether you guessed right.
2. Complete the description in the starter so it covers three different phrasings while not covering two near-miss phrasings.
3. Complete the body's workflow and pitfalls sections, writing the two most-violated rules of the team convention as pitfalls.
4. Copy the whole directory into your client's project-level skill directory, trigger it once with each of three phrasings, and watch it open up and output per your template.
5. Check the name, the description length, and the body line count against the spec, and record the three numbers in the worksheet.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward how a description is written and how triggering works, how a skill's body is layered, and installation locations and scope. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Narrow a repeated task down to a skill's boundary, and state what it should not handle
• Write a usable description following three rules — imperative mood, user intent, and a clear boundary
• Install a skill into a client's project-level or user-level directory, and confirm it is actually triggered
• Recite the three diagnostic steps for a skill that did not trigger, and explain why the first is whether it was scanned
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D3) we upgrade writing by feel into writing by method: three criteria for choosing a subject, two mature forms, four anti-patterns, and the most important thing — actually measuring a description's trigger rate with a set of positive and negative cases. Today you judged quality by trying three sentences yourself, which works with one skill and stops working by the tenth. Tomorrow gives you a ruler you can reuse.