Writing a Custom Agent Skill

Why Custom Agent Skills Matter

An AI agent that only answers questions is a chatbot. An agent that can execute repeatable, structured work is a team member. The difference often comes down to a single markdown file: a skill.

In our own cross-border sales operation, we moved from pasting prompts into ChatGPT to packaging prompts into tested skills that our agents run every day. The result: less drift, fewer hallucinated steps, and a predictable output format that feeds the next system. For operators who do not code, writing a custom skill is the fastest way to turn AI from a toy into a production tool—and you can build it without touching an API.

This article walks you through the anatomy of a skill, from a blank file to a tested, reusable instruction that an agent follows like a checklist. You will learn the five steps, see a worked example from our own sales floor, and grab a template you can adapt today.

What a SKILL.md Looks Like

Every skill lives in a directory with a single markdown file, conventionally named SKILL.md. Inside, you will find three things:

1. Frontmatter – a few lines at the top that give the skill a name and a description.
2. Instructions – numbered steps, constraints, and an output format that the agent must follow.
3. Optional resources – templates, scripts, or reference files next to SKILL.md.

The frontmatter description is the most important safety valve you control. An agent reads this description to decide *when* it should activate your skill. Write it like a trigger condition, not a mission statement. For example, instead of "helps with sales", write: "Use this skill when the user provides raw notes or a transcript from a sales call and asks for a follow-up message draft." That narrow definition prevents the skill from firing on unrelated requests.

Here is a minimal frontmatter (without code, just as you would type it):

name: sales-follow-up-draft description: Use when the user shares notes or a transcript from a sales conversation and requests a follow-up email or WhatsApp message. The user may say things like “write a follow-up” or “draft a follow-up message.”

After the frontmatter, the body of SKILL.md contains the actual instructions. These are always a series of steps, constraints, and a concrete output template. The agent reads them sequentially, so write them as an operator, not a poet: short sentences, verbs first, no ambiguity.

How to Write and Ship a Skill (Five Steps)

We follow a five-step development process we call five-step-dev, which we published as an example skill inside our open agent skills library at (/en/products/365skill). The same loop applies whether you are building a sales skill, a growth analysis skill, or a logistics agent.

Step 1 – Create the skill directory and SKILL.md. Pick a short, descriptive folder name (e.g., sales-follow-up). Inside, create the SKILL.md file with empty frontmatter.

Step 2 – Write the frontmatter (name + description). Name is a machine-readable slug. Description is the activation switch. Test your description by asking yourself: "If I were the agent, would I map this exact user sentence to this skill?" If you cannot answer yes with confidence, the description is too vague.

The most common mistake we see: a description that reads like a product tagline ("boosts productivity") rather than a use-case trigger. That kind of description either never fires or fires on everything—both break the experience.

Step 3 – Write the instruction body. Use a numbered list. Each step tells the agent exactly what to extract, transform, or generate. Add constraints: word limits, tone guidelines, forbidden phrases. Then specify the output format, ideally with a short template like:

• Subject line (if email): ...
• Greeting: ...
• Body (max 120 words): ...
• Next-step call-to-action: ...

Constraints prevent the agent from going creative. For production skills on our floor, we found that a hard word limit cuts hallucination by a measurable margin.

Step 4 – Package resources. If the skill needs a fixed template or a CSV of product names, drop that file into the same directory and reference it in the steps. Keep it simple: one or two files at most.

Step 5 – Test and create evals. Prepare three or four real inputs that should trigger the skill. Run them through your agent and check that the output matches the shape you defined. Save those inputs and expected outputs as a simple evals set; run them again after any change. Without evals, a skill can quietly degrade as the underlying model updates, and nobody notices until it causes a real-world mistake.

In our 365Skill library, the five-step-retro skill shows exactly how we pair a production skill with a retrospective checklist so that every run validates itself. You can see both examples live.

A Real Example: Sales Follow-up Draft Skill

Let’s walk through a concrete skill we built for our WhatsApp sales team using Sellenca. The business problem: after a sales call, a rep has messy notes in three languages. We want the agent to draft a follow-up message in clean English or Spanish that keeps deals moving.

Skill frontmatter:

name: follow-up-from-call-notes description: Use when the user pastes raw notes or a transcript from a recent sales conversation and asks for a follow-up WhatsApp message or email. The user will say things like “draft a follow-up to this lead” or “write a summary message based on these notes.”

Skill steps (condensed):

1. Read the notes. Identify: the contact’s name, the product discussed (if any), the main objection or concern, the agreed next step, and the expected timeline.
2. Determine the language of the notes. The output must be in the same language, unless the user explicitly asks for a different one.
3. Draft a short message in the brand voice: friendly, direct, no emojis, no sales pressure. Structure:

- Opening line acknowledges the previous conversation. - One sentence that handles the objection or confirms the next step. - Clear, short call-to-action (e.g., “I’ll send over the quotation by 3pm today”).

4. Check length: the whole message must stay under 140 words. If it is longer, cut the weakest sentence.

Output format template:

Greeting: Hi [Name], Body: [drafted message] Signature: Best, [Seller’s name]

We tested it with five real transcripts. Four produced a usable draft with zero manual edits. The fifth needed one rephrase because the agent misidentified the product. We added a constraint to the skill: "If the product is ambiguous, ask before drafting." After that, it passed every evals run and went into live use across 10 sales reps. In the first month, follow-up response rates rose by about 12% because messages went out faster and sounded more relevant—no extra hire required.

Common Mistakes (and How to Avoid Them)

These are the three failure patterns we see repeatedly, both on our own floor and when teams adopt our agent orchestration platform 365AIOrg to deploy skills.

The fix for all three is the same discipline that works in operations: treat a skill like a checklist, not a conversation. When we look at the production skills in our own agent skills library, every single one that survived more than a month follows this pattern.

FAQ

What is the difference between a skill and a prompt?

A prompt is a one-off instruction you paste into a chat. A skill is a packaged, versioned set of instructions that an agent loads automatically when a specific trigger condition is met. It is reusable, testable, and can include resource files—prompts alone cannot do that reliably in production.

How many skills should I write?

Start with two or three for the highest-volume, most repetitive tasks your team does every day. In our sales operations, we have fewer than 10 production skills, and they cover over 80% of AI-assisted actions. More skills add management overhead; fewer, and you leave easy wins on the table.

Can I share skills across different teams?

Yes. A skill is just a folder. You can version it in a shared repo—like our open library at (/en/products/365skill)—and let any compatible agent platform load it. Make sure the description and steps are general enough for each team’s context, or parameterize with a config file in the skill directory.

How do I ensure a skill does not break over time?

Build a small evals set of example inputs and expected outputs. Re-run it after you change the skill or when the underlying AI model updates. We recommend doing this at least once a month. Without it, skill degradation is silent but inevitable.

---

Ready to turn your operating know-how into skills that run 24/7? Start with our open Agent Skills Library for templates and real production examples. Or, if you want to see how we weave skills into a full agent orchestration workflow—from sales to growth—explore the full product lineup and book a free consult at (/en/contact).