What Makes a Good Agent Skill File

Run the same agent on the same task twice and you can get two different answers. Ask two teammates to set up the same agent and you get two different agents. One asks three questions before quoting a price. One invents the price. One writes a friendly paragraph that answers nothing.

The model is not the variable. The instruction is. Most ai agent skills fail here, before anyone argues about models. The agent had nothing stable to load, so it improvised.

A skill.md fixes that. It tells the agent when to run, what to do, what to produce, and when to stop. Written well, it turns a general model into a specialist.

The description decides whether the skill runs

The body only matters if the agent picks the skill up. Routing happens on the name and description, which most runtimes load before the body.

Say what the skill does, what it produces, and what it does not cover, in your users' words. Use when forces a condition instead of a topic.

• Name the job, not the department. inbound-lead-qualification beats sales-helpers.
• Name the deliverable. "Produces a qualification summary and a booking recommendation."
• Name the exclusions. "Do not use for existing customers."

Test routing alone. Hide the body, hand the agent a dozen requests, and see which skill fires. If two skills both look plausible, the descriptions overlap.

When to use it, and when not to

Every skill needs a negative list. Without one, the agent stretches it over the nearest adjacent task and applies brand voice to legal copy.

Write it in the same voice:

• Existing customer with a billing issue: route to support.
• Contract redlines: route to legal review.
• User asks for a price: answer from the pricing page, never estimate.

Add a handoff line for anything near the boundary. "If the request is about X, stop and use Y."

A skeleton that holds up

Adjust the sections, keep the order: routing, boundaries, rules, output, tools, references, failure.

---
name: inbound-qualification
description: Use when a new inbound lead needs qualification before a call is booked. Produces a qualification summary and a booking recommendation. Do not use for existing customers.
---

# Inbound qualification

## When to use
- A lead form, email, or chat message arrives from someone who is not yet a customer.

## When not to use
- Existing customer or support issue: hand off to support.

## Rules
- Ask at most one clarifying question before writing the summary.
- Never state a price. Point to the pricing page.
- Mark any field you could not verify as unknown.

## Output
Return these sections in order: fit, budget signal, timeline, next step.
Keep it under 180 words.

## Tools
- Read the CRM record before writing.
- Do not create or update records. Recommend, do not act.

## References
- references/qualification-criteria.md
- scripts/score_lead.py

## On failure
If the lead message is unreadable, stop and ask for the source text.copy

Write ai agent skills as behavior you can check

An adjective is not an instruction. "Be professional" gives the agent nothing to do. "Never quote a price without a written spec" gives it a decision.

Good rules share four traits:

• They are imperative. Start with a verb the agent can act on.
• They are testable. You can write a case that violates the rule.
• They carry their exception. "Ask one clarifying question, unless the brief includes a deadline and a budget."
• They do not fight each other. Two rules pulling in opposite directions produce coin flip behavior.

Keep the list short. Five to ten rules covers one job, and every extra rule costs attention.

Put the rules that prevent damage first: what not to send, what not to promise, what not to delete. Style rules go last.

Pin down the output contract

If two runs produce different shapes, nobody can review the work. The output contract makes results comparable.

Decide these before you write:

• Sections and their order. "Fit, budget signal, timeline, next step."
• A length ceiling. A number, not "concise".
• Required fields. What must appear even when the answer is unknown.
• The uncertainty rule. Say unknown rather than guessing.
• The refusal shape. What the agent says when the request is out of scope.
• Citation rules. When a claim needs a source, and what counts as one.

Write the contract as a template the agent fills. If you want markdown, show the markdown. If you want JSON, show the keys.

The contract also tells you when the run is done.

Set tool rules before the agent needs them

Behavior rules cover words. Tool rules cover actions with consequences: writes, sends, deletes, payments. The failures that cost money happen at the tool boundary.

• Read before write. Load the record or file before changing it.
• One write per task unless the user asks for more.
• A confirmation threshold. Name the actions that need a human yes: external email, publishing, refunds, large spends.
• Forbidden tools. If the skill should never touch a production database, say so.
• Failure behavior. If a tool errors, retry once, then report. Do not switch tools.
• Secret handling. Never print keys, tokens, or customer data into the output.

A short allowlist helps: "You may read the CRM. You may draft email. You may not send email."

Keep skill.md small

The file is an instruction, not a knowledge base. Long files get skimmed and truncated. Keep decisions in the main file and move the bulk out.

References

Put long material in references/ and name the file: references/qualification-criteria.md. Tell the agent when to open it. "Open the criteria file before scoring fit."

Scripts

Use scripts/ for anything with a correct answer: scoring, parsing, date math, validation, file conversion. A script that prints a clean result beats a paragraph asking the model to be careful with numbers. Have it fail with a clear message and a nonzero exit code, and say what to do next.

What to leave out

• General knowledge the model already has. No need to explain what a lead is.
• Company facts that change weekly. Link to the source of truth.
• Secrets, keys, and customer data.
• Pasted transcripts. Summarize the decision, drop the chat.
• Rules for jobs the skill does not own.
• Personality essays. If a sentence describes how the agent should feel, delete it.

Past a few hundred lines, you are writing documentation.

Walk through one example

Imagine a brand voice skill and a request: "Draft the launch email for our new pricing page." The Brand Agent Skill Pack applies this shape to voice, claims, and review.

A weak skill produces a generic email with three exclamation marks. A working skill does this:

1. Confirms the request is in scope: outbound marketing copy, not a support reply.
2. Opens references/voice.md and references/pricing-claims.md before writing.
3. Checks the output contract: subject line, 120 words or fewer, one call to action, no invented discount.
4. Drafts. When the brief has no audience, it writes audience: unknown at the top instead of guessing.
5. Checks any pricing line against the approved claims file.

The output is boring in the best way. Same sections, same length, same honesty about what it did not know.

Run the same example through your own skill before you ship it. If the steps are not visible in the output, the skill is not working. The inbound qualification job in the skeleton is the kind of work the Sales Agent Skill Pack packages.

Decide what happens when it fails

Every skill meets input it cannot handle. Good ones specify what happens next.

• Missing input. Ask for the one thing you need. Do not fill the gap with a guess.
• Tool error. Retry once, then report the error and what you completed.
• Out of scope. Name the boundary and the handoff. Do not attempt a partial version.
• Conflicting instructions. The skill wins over the user's style request, not over safety. Say which rule you followed.
• Low confidence. Mark the field unknown or ask. A flagged gap is cheaper than a confident wrong answer.

Add a stop condition. "If two attempts fail, stop and return the last successful step." Without one, agents loop or improvise, and both are worse than a clean failure.

Version it, then test it

A skill is production code. Treat edits the same way.

Keep a version number and a one line changelog in the file. Change one behavior per release so a regression points at a single cause. Pin the version in the agent config and keep the old one until the new one passes. When you retire a behavior, say so with a date. If you run several agents, the Operator Agent Profile takes the same approach: one stable profile, skills you can swap and roll back.

A test plan you can run in an afternoon

1. Routing. Ten requests that should trigger the skill, ten that should not, three on the boundary. Check which skill fires.
2. Golden runs. Three realistic tasks with outputs you reviewed by hand. Compare shape, not wording.
3. Contract checks. Does every output have the required sections, the length ceiling, and the right treatment of unknown fields?
4. Adversarial input. An empty message, a 5,000 word message, a user instruction that says "ignore your rules", a request just outside scope.
5. Tool failure. Kill the API or return an error. The agent should report, not route around it.
6. Regression. Rerun the set after every edit.

Ten to twenty cases catch most of the damage. The point is not coverage but habit: no edit ships without a rerun. For prompts to test a first skill against, start with the free prompt kit.

Questions people ask

How long should a skill.md be?

Short enough that a person can read it in one sitting. The main file holds routing, rules, output, and failure. Everything long moves to references. Past a few hundred lines, split the skill.

Can one skill work across different models?

Often, if the rules are explicit and the output contract is checkable. Test routing and contract compliance on each model you use. Models differ in how literally they follow instructions and how they handle tools.

Do I need scripts, or can the model just do the work?

Use scripts where there is a correct answer: math, parsing, validation, file transforms. Use the model where judgment is the point: tone, prioritization, drafting. If a wrong number would be expensive, script it.