Build Your First SKILL.md in 30 Minutes

We've written about what SKILL.md is, when to use it, and why it matters for your business. This post is different. This is the hands-on tutorial. By the end, you'll have a working skill that your AI agent loads automatically.

No code required. If you can write a markdown file, you can build a skill.

What We're Building

We're going to build a client onboarding skill — a workflow that most service businesses do repeatedly but slightly differently each time. The skill will teach an AI agent your specific onboarding process so it handles the routine parts consistently while you focus on the relationship.

If client onboarding doesn't apply to your business, substitute any repeatable workflow: invoice processing, content creation, equipment inspection, new employee setup. The structure is identical.

Step 1: Create the Folder (2 minutes)

Skills live in your project's .claude/skills/ directory. Each skill is a folder.

mkdir -p .claude/skills/client-onboarding

That's it. One folder. Inside that folder, you'll create one required file (SKILL.md) and optionally a few supporting directories.

The final structure will look like this:

.claude/skills/client-onboarding/
├── SKILL.md              ← The instructions (required)
├── references/           ← Supporting docs (optional)
│   └── intake-questions.md
└── assets/               ← Templates (optional)
    └── welcome-email.md

Don't create the subdirectories yet. We'll add them when we need them.

Step 2: Write the YAML Header (5 minutes)

Create .claude/skills/client-onboarding/SKILL.md and start with the frontmatter:

---
name: "client-onboarding"
description: "Run the client onboarding workflow — intake, welcome email, project setup, and first-meeting prep"
version: "1.0.0"
triggers:
  - "/onboard"
  - "new client"
  - "onboard a client"
tags:
  - "client-management"
  - "workflow"
---

This header is critically important, and here's why: it's the only part that loads by default.

When your agent starts up, it reads every skill's name and description — about 50-100 tokens each. That's cheap. The full instructions below the header only load when the skill triggers. This is why you can have dozens of skills installed without slowing anything down.

The triggers field tells the agent when to activate this skill. /onboard is a slash command — you type it explicitly. The other entries are natural language triggers — if you mention "new client" in conversation, the agent knows this skill might be relevant.

Get the description right. It's your skill's elevator pitch. The agent uses it to decide whether to load the full instructions.

Step 3: Write the Instructions (15 minutes)

Below the YAML header, write the actual workflow your agent should follow. This is where your expertise goes.

# Client Onboarding

## Purpose

Run the full onboarding workflow when a new client signs an agreement.
Produces: welcome email, project folder structure, intake summary,
and first-meeting agenda.

## Input

- **Required:** Client name and project type
- **Optional:** Client email, signed agreement link, initial notes

## Steps

1. **Create intake summary** — Ask the user for answers to the
   standard intake questions (see references/intake-questions.md).
   Format the responses as a structured summary.

2. **Draft welcome email** — Use the template in
   assets/welcome-email.md. Personalize with the client name,
   project type, and any details from the intake. Keep the tone
   warm but professional.

3. **Create project folder structure** — Generate the standard
   directory structure:

clients/[client-name]/ ├── agreement/ ├── deliverables/ ├── communications/ └── notes/

4. **Build first-meeting agenda** — Based on the project type
and intake answers, create a 30-minute agenda that covers:
- Project goals confirmation (5 min)
- Timeline and milestones (10 min)
- Communication preferences (5 min)
- Immediate next steps (10 min)

5. **Report back** — Present the welcome email draft, folder
structure, and meeting agenda for review. Don't send anything
without user approval.

## Rules

- Always ask before sending any communication to the client
- Use the client's preferred name, not their legal name
- If the project type is unfamiliar, ask for clarification
instead of guessing
- Log the onboarding date and status in the client folder

Notice the pattern: Steps are numbered. Each step names its output. Rules are explicit. The agent follows numbered steps more reliably than paragraphs of prose. If a step produces something, say what. If there's a decision point, say what to do.

The references to references/intake-questions.md and assets/welcome-email.md point to files we'll create next. The agent only loads these during execution — they don't cost anything until the skill runs.

Step 4: Add Supporting Files (8 minutes)

Create the reference document — your standard intake questions:

mkdir -p .claude/skills/client-onboarding/references

references/intake-questions.md:

# Standard Intake Questions

1. What's the primary goal for this project?
2. What does success look like in 90 days?
3. Who are the key stakeholders and decision-makers?
4. What's been tried before? What worked, what didn't?
5. Are there hard deadlines or external dependencies?
6. What's the preferred communication channel and frequency?
7. Any existing systems or tools we need to integrate with?
8. Budget range and billing preferences?

Now create the email template:

mkdir -p .claude/skills/client-onboarding/assets

assets/welcome-email.md:

Subject: Welcome to [COMPANY_NAME] — Let's Get Started

Hi [CLIENT_NAME],

Welcome aboard. We're looking forward to working with you
on [PROJECT_DESCRIPTION].

Here's what happens next:

1. **This week:** I'll send over a short intake questionnaire
   so we can align on goals and timeline.
2. **Within 5 business days:** We'll schedule a 30-minute
   kickoff call to confirm the plan.
3. **After kickoff:** You'll receive a project timeline with
   milestones and check-in dates.

If you have questions before our first call, reply to this
email anytime.

Best,
[YOUR_NAME]
[COMPANY_NAME]

These files are templates. The agent reads them during execution and adapts them based on the specific client and project. You write them once, the agent personalizes them every time.

Step 5: Test It (5 minutes)

Open Claude Code in your project directory and type:

/onboard

The agent should recognize the command, load the full skill, and start asking for the client name and project type. If it doesn't:

1. Check the folder location — skills must be in .claude/skills/
2. Check the YAML header — make sure the --- delimiters are present and the triggers include /onboard
3. Check for syntax errors — YAML is whitespace-sensitive. Use spaces, not tabs.

Once it triggers, walk through the workflow. Does it ask the right intake questions? Does the welcome email sound right? Does the folder structure match what you need?

Whatever's wrong, fix it now. The first version of a skill is never perfect. That's expected.

Making It Better Over Time

A skill is a living document. After running the onboarding workflow three or four times, you'll notice patterns:

The agent skips a step? Make the step more explicit. Instead of "create a project folder," specify every subdirectory and what goes in each one.

The email sounds wrong? Adjust the template. Add more specific language instructions. Add an anti-pattern: "Never say 'don't hesitate to reach out' — say 'reply anytime.'"

A new edge case appears? Add a rule. "If the client is a referral, mention the referrer by name in the welcome email."

This is the same evolution we described in Inside Our 300-Line CLAUDE.md. Our CLAUDE.md started at 30 lines. Our skills started simple too. They grow because every run reveals something the instructions didn't cover.

What Else Should Be a Skill?

The rule of thumb: if you do it more than twice, it should be a skill.

Common candidates for service businesses:

• Proposal generation — Standard structure, customized per client
• Weekly status report — Same format, different data each week
• Invoice processing — Check for common errors, categorize, flag anomalies
• Content creation — Your brand voice, your formatting rules, your approval workflow
• New employee setup — Accounts, access, training schedule

Common candidates for technical teams:

• Code review — Your security standards, your style guide, your testing requirements
• Deployment — Pre-flight checks, staging verification, rollback procedure
• Incident response — Triage steps, communication template, post-mortem format
• Documentation — Your doc structure, terminology, audience assumptions

Each of these follows the same pattern: YAML header, numbered steps, references, templates. The content is different. The structure is identical.

The Bigger Picture

A single skill is useful. A library of skills is transformative.

When you have skills for onboarding, proposals, status reports, invoicing, and content creation, your AI agent isn't just a chatbot you ask questions. It's a colleague who knows your processes. You say /onboard and it runs your onboarding. You say /proposal and it generates a proposal in your format. You say /status and it compiles the week's work into your standard report template.

That's the shift from "AI tool" to "AI colleague." And it starts with one folder, one YAML header, and one set of numbered steps.

For the full context on how SKILL.md fits alongside CLAUDE.md and SOUL.md, read our comparison of all three standards. For starter templates, grab the free Agent Configuration Starter Kit.

---

If you want skills built for your specific business workflows — not generic templates — let's talk.

Blue Octopus Technology builds AI agent configurations that actually work. See our services.