Beginner's Guide to Building Your First Custom AI Skill (2026)

What a custom Skill actually is

A Skill is a folder of files on your disk. The folder has a specific name (used to invoke the Skill), contains at minimum one file called SKILL.md, and optionally contains supporting files that SKILL.md references. That's it. There's no build step, no package to publish, no runtime to configure. You drop the folder into your AI client's Skills directory and the Skill exists.

The reason this works — and the reason Skills are portable across every major AI client — is that the format is deliberately boring. Plain text, plain markdown, plain folders. Any AI provider that reads the format can use your Skill; any human who opens the folder can understand it. That boringness is the feature.

If you've written a Notion doc or edited a README on GitHub, you have all the technical skills required to build a Skill. What you actually need to bring is knowing what you want the AI to do consistently. That's the hard part — and it's a thinking problem, not a coding problem.

When to build your own vs. use an existing Skill

Before spending 45 minutes building something, spend two minutes searching. Our Skills directory has 207 Skills across 10 categories, and one of them is likely close to what you need. The build-vs-download decision is genuinely simple:

• Use an existing Skill if it covers the task and you can supply your own voice samples or configuration files to personalize it. Most Skills in the directory are built to be personalized.
• Fork an existing Skill (download it, rename it, edit) if 80% of what it does matches your need and you want to change the other 20%. Fastest path to a custom Skill.
• Build from scratch if the task is genuinely specific to your work (your team's status-update format, your company's proposal template, your niche industry's compliance checklist) and no existing Skill fits.

The example this guide walks through — a Weekly Status Update Skill — is a build-from-scratch case, because every team's status format is different enough that a generic version isn't useful.

The anatomy of a Skill

A minimal Skill has one file. A full Skill has five or six, all optional except the first. Here's the standard layout:

Everything except SKILL.md is your call — add files as they become useful, skip them if they don't. Some Skills work perfectly with just SKILL.md. Others (voice-matched writing especially) need at least a voice-samples file to work well.

The folder name matters: it becomes the Skill's callable name. Use kebab-case (weekly-status-update), no spaces, no capital letters — conventions that keep the Skill compatible with every AI client.

Writing your first SKILL.md

The SKILL.md file has two parts: a YAML frontmatter header (the metadata the AI reads to know when to use the Skill) and a markdown body (the instructions).

Here's the full file for our Weekly Status Update Skill:

---
name: weekly-status-update
description: "Turn a rough bullet list of the week's work into a
  polished team status update matching our template and voice.
  Use when the user provides notes, bullets, or fragments of
  what they did this week and asks for a status update, weekly
  report, or Friday update."
---

# Weekly Status Update

## When to use this Skill

The user provides rough notes about their week and needs a polished
status update to send to their team. Common triggers: "write my
weekly update," "draft my Friday report," or a pasted bullet list
followed by "clean this up."

## How to write it

1. Read `template.md` to see the exact structure the output must follow.
2. Read `voice-samples.md` to match the tone of previous updates.
3. Read `team-context.md` for who's on the team and what priorities matter.
4. Group the user's notes into the template's sections (Shipped,
   In Progress, Blocked, Next Week). Move items to the right section
   even if the user grouped them differently.
5. For each item, add one clarifying sentence of context — don't just
   restate the bullet. Assume the reader hasn't seen the item before.
6. Flag anything in Blocked with the specific person or decision needed.
7. Keep the whole output under 350 words. Cut anything that doesn't help
   the team make decisions this week.

## What NOT to do

- Don't invent items the user didn't mention. If the notes are thin,
  ask what else happened.
- Don't use corporate jargon (leverage, synergy, circle back).
- Don't reorder priorities — the user's ordering signals importance.
- Don't include personal life notes even if the user mentions them.

Two things to notice about this file. First, the description in the YAML header is not just a summary — it's a trigger. The AI reads it to decide when to invoke this Skill automatically. If the description is vague ("helps with weekly reports"), the AI won't know when to use it. If it's specific ("Use when the user provides notes, bullets, or fragments of what they did this week..."), the AI recognizes the situation instantly.

Second, the instructions are opinionated. Notice the "What NOT to do" section. A Skill without prohibitions runs into the same problem every long prompt does: the AI drifts toward its defaults. Explicit negative rules keep it aligned.

Adding supporting files

Supporting files are what turn a decent Skill into a great one. For the Weekly Status Update Skill, three files pull weight:

1voice-samples.md. Paste in 3–5 of your past status updates — the good ones. The AI reads them as reference for tone, sentence rhythm, and structural preferences. This single file is the difference between output that reads like your team and output that reads like a template.

2template.md. The literal structure the output must follow. For a status update, that might be four sections (Shipped, In Progress, Blocked, Next Week) with a specific format for each item. Templates work best when they show the format with placeholders, not just describe it:

## Shipped
- [Item] — [one-line context of why it matters]

## In Progress
- [Item] — [expected completion, e.g., "shipping Mon"]

## Blocked
- [Item] — blocked on [person or decision]

## Next Week
- [Item]

3team-context.md. A short file describing the team — who reports to whom, what the current quarter's priorities are, what shorthand terms your team uses that a generic AI wouldn't know. Update this quarterly, not weekly.

Supporting files earn their keep by giving the AI context that can't fit in a single prompt. If you find yourself pasting the same background material into your prompts repeatedly, that material belongs in a supporting file.

Testing your Skill

Before trusting a Skill on real work, run three deliberate tests. Fifteen minutes now saves an hour later.

• Invoke it directly. Say "Use the Weekly Status Update Skill to draft my update from these notes: [paste]" and check the output against the template.
• Test auto-invocation. Say "Here's what I did this week—can you turn this into my Friday update?" without naming the Skill. Did the AI recognize the trigger from your description? If not, the description isn't specific enough — tighten it.
• Test edge cases. Give it a thin week (three items). Give it a chaotic week (fifteen items in random order). Give it a week with something blocked. Each edge case reveals gaps in the instructions.

When something doesn't work, the fix is almost always in SKILL.md: add a rule, add an example, tighten a description. Iterate on the file, restart your AI client to reload the Skill, test again. A Skill that survives its first week of testing has been through 4–6 revisions. That's normal.

Versioning and sharing

Once your Skill works, you'll want to keep it working over time and probably share it. Both are simple.

Versioning: Add a version line to the top of SKILL.md (<!-- version: 1.2 -->) and a short changelog at the bottom. When you change the Skill, bump the version and add a line to the changelog. This matters especially when the Skill is shared — teammates need to know when to reload.

Sharing: Skills are folders. Zip the folder, share it. Recipients drop it in their Skills directory. Teams often keep shared Skills in a Git repo or a shared Google Drive folder, with each Skill in its own subfolder. Version control gives you review, history, and rollback for free.

Publishing: If your Skill is useful beyond your team, consider submitting it to our directory via /contribute/. We regularly feature reader-built Skills — the best ones get promoted to the front page of their category.

Common beginner mistakes

• Vague description in the YAML header. If the AI can't tell when your Skill applies, it won't invoke it. Write descriptions that describe the situation, not just the task.
• Instructions with no prohibitions. "What NOT to do" sections keep the AI aligned. Skipping them means the AI drifts back to defaults.
• Missing voice samples for voice-matched tasks. If the output needs to sound like you, provide samples. There's no shortcut.
• Building a Skill for a one-time task. Skills pay off when reused. If the task happens once a quarter, a prompt template is fine. Save Skills for weekly or daily work.
• Not restarting the client after edits. Skills load at startup. Edits don't take effect until restart.

Where to go next

You've built your first Skill. Two natural next steps:

• Build a second Skill by forking a directory Skill — download something from our Skills directory that's close to a task you do, then adapt it. Second Skill is always faster than the first.
• Read our Learn guides for deeper patterns — especially the queued voice-samples guide and the workflow-composition patterns.

Or just start writing. The best custom Skills come from noticing what you're doing repeatedly and writing down the rules you've been carrying in your head. The AI is happy to follow them — if you take the time to write them out.

Frequently asked questions