How to Teach Your AI Agent a New Trick: Building a Custom Skill in 15 Minutes

You know that guy at the mall in the red suit? He's amazing at the classics. "Ho ho ho!" Nailed it. Asking kids what they want for Christmas? Decades of experience. But when a seven-year-old asks for a Squishmallow in the shade "somewhere between lavender and periwinkle, but NOT the axolotl," he just smiles and nods. He has no idea what any of those words mean. Now imagine you slip him a laminated cheat sheet with photos, prices, and exact store locations. Suddenly he's giving parents aisle numbers and SKU codes. Same Santa, completely different level of usefulness.

That's what we're doing today. You're going to teach your AI agent something specific to your actual work, and it'll take about as long as your lunch break.

Why Your AI Keeps Saying "I'll Do My Best" (Then Doesn't)

AI agents arrive with impressive general knowledge. They can write emails, explain concepts, summarize documents. But they don't know anything about YOUR world. They've never seen your company's spreadsheet format. They don't know that "adjusted revenue" means something different in your department than it does everywhere else. They've certainly never heard of a Squishmallow.

Without specific instructions, the agent improvises. It guesses. It produces something that looks roughly right but misses the details that actually matter. You wanted periwinkle, you got blue.

A skill is packaged instructions combined with resources (data files, code snippets, templates, access to specific tools) that teach the agent how to handle one particular task your way. Not the general way. YOUR way.

The difference between an AI that's "pretty helpful sometimes" and one that actually saves you three hours every week comes down to whether it has the right cheat sheet.

The Two Things Every Skill Needs (Instructions and Props)

First, you need clear, step-by-step instructions. Not vague guidance. Actual steps that tell the agent exactly what to do and in what order. "Pull data from these specific columns. Calculate this specific thing. Format the output this specific way." The kind of instructions you'd give someone who will ask zero follow-up questions because they're not allowed to.

Second, you need the actual resources required to execute those instructions. Code snippets the agent should run. Data files it should read. Templates it should fill in. API access it needs to fetch information.

Santa needs to know what a Squishmallow IS (the concept, the variations, the current hot sellers) and where to actually get one (aisle 7, third shelf, also available online with two-day shipping). One without the other leaves him either knowledgeable but useless or confident but wrong.

Every AI tool that supports skills does some version of this pairing. To make it concrete, the rest of this guide uses Claude Code, the version of Claude that runs in your terminal, because its skills are just files on your computer and you can read them with your own eyes. A skill there is a folder. Inside the folder is a file called SKILL.md holding the instructions, and any other file you drop in beside it becomes one of the props.

Say you're building a skill that generates your weekly email report. The instructions are "pull data from columns B through F, calculate percent change from last week, format as three bullet points highlighting the biggest changes, use casual but professional tone." The resources are your actual spreadsheet template and the email format you always use. Both pieces, one package.

Building Your First Cheat Sheet (The 15-Minute Version)

Pick one task you do every week that follows the same steps every time. Maybe it's formatting meeting notes. Maybe it's pulling numbers for a status update. Something repetitive enough that you could do it half-asleep.

Write down those steps in plain English. Pretend you're training someone who takes everything literally and never asks clarifying questions. "Open the attached template. Sum column C. Compare to last week's total. Write three bullet points. The first bullet should highlight the biggest change. Use percentages, not decimals. Keep it under 100 words."

Now gather the resources. The spreadsheet template. The email format. The data source. Whatever the agent needs to actually execute those steps. If you reference "the template" in your instructions, you need to attach the actual template file.

Now make the folder. The name you give it becomes the command you type later, so keep it short and obvious:

mkdir -p ~/.claude/skills/weekly-report

Inside that folder, create a file named SKILL.md. The top of the file is a small block of settings fenced by three dashes, and the rest is the instructions themselves:

---
description: "Builds the Friday sales email from the weekly numbers. Use when the user asks for the weekly report or the Friday email."
---

## Instructions

1. Read numbers.csv in this folder.
2. Sum column C and compare it to last week's total.
3. Write exactly three bullet points, biggest change first.
4. Use percentages with the % symbol and no decimals.
5. Keep the whole thing under 100 words, casual but professional.

That description line is doing more work than it looks. It's how Claude decides on its own that this skill is the right one for what you just asked, so write it as "what this does, and when to reach for it" rather than a title. Everything in the settings block is optional, but this is the one worth getting right.

Then drop your props in the same folder, the numbers.csv your instructions reference, a template, whatever the steps actually need. Put it where you said it would be.

Test it by typing /weekly-report. You can also just ask for the Friday email in plain English and let Claude match your request to that description. The first test, you'll spot something you forgot to specify. You'll add it. Second test usually works.

Two details worth knowing before you build a pile of these. A skill in ~/.claude/skills/ follows you into every project, while one in a project's own .claude/skills/ folder stays put and ships to whoever clones the repo, which is the one you want for anything team specific. And skill instructions cost you nothing until they're actually used, so a long, fussy, deeply specific skill is not a tax on every other conversation you have.

When Your Skill Bombs (And How to Fix It Fast)

First test, the agent does something confidently and completely wrong. It sends parents to the toy aisle from 1987 where Squishmallows definitely do not exist and never have.

Your instructions were too vague. You assumed knowledge the agent doesn't have. You said "format it nicely" when you meant "use bullet points with bold headers and no more than 50 characters per line." Add one example showing the exact output you want. Show him an actual photo so he knows what he's looking for.

Second test, the agent says it can't access something. Your resource file isn't actually attached, or it's in a format the agent can't read, or you referenced "the Q3 template" but attached a file named "sales_data_final_v2.csv."

Check your attachments. Make sure file names match what your instructions say. Confirm the agent can actually open that file type.

Your report-generating skill outputs 0.15 instead of 15% because you didn't specify format. You add "format all percentages with the % symbol, no decimals" and test again. This time it works. Third time is usually the charm because you've made all the implicit stuff explicit.

So What Can YOU Do With This?

Create a "Weekly Report Generator" skill with your actual spreadsheet format and email template. Every Friday at 3pm becomes a three-minute task instead of a thirty-minute one.

Build a "Meeting Notes Formatter" that takes your messy real-time notes and outputs them in your company's standard format with action items, decisions, and follow-ups properly categorized.

Make a "Customer Email Responder" skill loaded with your FAQ answers, your company's tone guidelines, and examples of great responses. Handle the routine questions in seconds, spend your time on the complex ones.

Design a "Data Cleanup" skill that knows your specific column names, understands your validation rules, and fixes the recurring errors in that one report everyone uses but nobody wants to maintain.

Any task you do the same way more than twice a month is a skill waiting to happen. A marketing manager creates a "Social Post Analyzer" skill with their brand guidelines and competitor examples. What used to take thirty minutes of review now takes three minutes of tweaking AI output.

TL;DR

• A skill packages step-by-step instructions with the actual resources (templates, data files, code) an AI agent needs to handle a specific task in your workflow
• In Claude Code a skill is just a folder holding a SKILL.md file, where a short description tells Claude when to reach for it and the numbered steps tell it what to do
• Build one in 15 minutes by picking a repetitive task, writing the steps in plain English like you're training someone who asks no questions, dropping your files in beside them, and testing twice
• First test will probably fail because you assumed knowledge or forgot to attach something. Add examples and check your resources are actually there
• Any task you do the same way twice a month is worth automating into a skill that saves you hours every week

After all, nobody wants to be the Santa who confidently directs parents to the Cabbage Patch Kids when the kid specifically asked for the purple Squishmallow unicorn.