How to Write a Good AI Agent Skill

A good AI agent skill changes what the agent does next. It gives the agent a clear trigger, the context to inspect, a workflow to follow, and a way to know when the work is finished.

That is the practical answer for anyone searching how to write a good AI agent skill: keep it concise, make it discoverable, test it in real usage, and remove any line that leaves the agent's behavior unchanged.

Matt Pocock has been pushing this point with unusual clarity. In a recent post on X, he calls out the kind of lines that fill weak skills:

Make the commit message very detailed
Be thorough
Make the implementation easy to read

His verdict is short: "They're no-ops."

That test is brutal in the best way. A line like "be thorough" sounds responsible. The agent was already trying to be thorough. A line like "Before asking the user, inspect the conversation history, files, documents, connectors, and WebSearch" changes the sequence of work.

That is what a skill is for.

What is an AI agent skill?

An AI agent skill is a reusable instruction set for a repeated workflow. In Claude, that often means a folder with a SKILL.md file. In Codex, Claude Cowork, and other agent harnesses, the exact packaging can vary. The useful idea travels: a skill gives the agent a specific operating pattern it can load when the work appears.

The best skills are small pieces of operational memory. They answer six questions:

1. When should the agent use this?
2. What should the agent inspect before acting?
3. What steps should it follow?
4. Which tools, files, or references matter?
5. Which decisions require a person?
6. How should the result be checked?

This is why skills belong in the broader move toward AI-native companies. If a person on your team keeps typing the same setup, correcting the same miss, or explaining the same workflow, that is a signal. The workflow wants to become reusable.

How to write a good AI agent skill

Start with the repeated work. A weekly report. A research brief. A plan critique. A support triage. A spreadsheet cleanup. A launch checklist. A client prep memo.

Once you can name the workflow, write only the instructions that change how the agent handles it.

1. Make the description do real routing work

The description is how the agent decides whether to load the skill. Treat it like a routing rule.

Weak:

description: Helps with documents

Useful:

description: >
  Reviews an AI workflow plan by asking one decision-focused question at a time.
  Use when the user wants to stress-test a plan, get grilled on a design, or
  prepare implementation inputs.

Good descriptions include the task, the moment, and the words a person might actually use. "Use when the user mentions grill me" is much stronger than a generic label like "planning helper."

2. Delete anything the agent already knows

This is the heart of Matt Pocock's writing-great-skills advice: prune no-ops, kill duplication, and keep the words that move behavior.

An agent already knows that output should be clear. It already knows that a summary should be useful. It already knows what a PDF is. Spend the skill on the part it cannot infer from general competence.

No-op:

Make the final answer easy to read.

Behavior-changing:

Lead with findings ordered by severity. Include file and line references for each finding. Put the summary after the findings.

The second instruction changes the artifact. The first one adds mood lighting.

3. Set the right freedom level

Claude's official Skill authoring best practices are worth bookmarking. I revisit that page often, and I have pasted it into an agent when I wanted a fresh pass against the fundamentals.

One idea from that page is especially useful: match the amount of instruction to the fragility of the task.

Use high freedom for work that needs judgment, like a strategy review, writing critique, or research synthesis.

Use medium freedom when a preferred pattern exists, like a report structure or analysis template.

Use low freedom when mistakes are expensive, like migrations, data corrections, destructive commands, or exact validation steps.

Over-constraining a judgment task makes the agent stiff. Under-specifying a fragile task creates risk. A good skill chooses the lane.

4. Keep SKILL.md small and point to durable references

Put the trigger, core workflow, and critical rules in SKILL.md. Put longer examples, schemas, templates, and domain notes in nearby files the agent can open when needed.

One level is usually enough:

my-skill/
|-- SKILL.md
|-- references/
|   |-- examples.md
|   `-- field-taxonomy.md
`-- scripts/
    `-- validate-output.py

Deep chains make the agent hunt for context. Clear one-level references make the skill easier to use and easier to maintain.

5. Add a workflow when sequence matters

Some skills are just a few rules. Others need a sequence.

For a plan critique, a useful workflow might look like this:

1. Read the plan and available context.
2. Identify the highest-impact unresolved decision.
3. Ask one question about that decision.
4. Include your recommended answer.
5. Let the user's answer determine the next branch.
6. Stop when the decision tree is resolved or the remaining unknowns are explicit.

That is much sharper than "stress-test the plan." It tells the agent how the session should unfold.

6. Add validation loops where quality matters

If the work can fail silently, put a check inside the skill.

1. Make the change.
2. Run the validation command.
3. If validation fails, fix the cause and run it again.
4. Stop when validation passes or the blocker is explicit.

If a script already exists, tell the agent to run it. If the output format matters, give an example. If the agent should ask fewer questions, tell it what to inspect before interrupting the human.

7. Test with a fresh agent

Reading a skill tells you how it feels. A fresh agent tells you how it behaves.

Run the workflow without the skill first. Notice where the agent drifts, asks for things it could discover, skips validation, or produces the wrong shape. Then write the smallest skill that fixes the observed failure.

Test again in a fresh session. Watch whether the skill loads at the right time, whether the agent follows the references, and whether the output improves for the reason you intended.

Our favorite example: /grill-me

Our favorite skill is /grill-me, adapted from Matt Pocock's public skills work. Matt's /grill-me routes into /grilling. The move is simple and strong: make the agent interview you about a plan until the decision tree is resolved.

That is useful because agents often plan too early, and people often skip the uncomfortable branch. /grill-me slows the room down. One question. One decision. Then the next branch.

At Elios, we widened the pattern beyond software planning. Our version keeps Matt's core move and adds one important rule: before asking the human, inspect the available context. Conversation history. Files. Documents. Connectors. WebSearch.

That turns the human's role into judgment instead of lookup.

---
name: grill-me
description: >
  Interview the user relentlessly about a plan or design until reaching shared
  understanding, resolving each branch of the decision tree. Use when the user
  wants to stress-test a plan, get grilled on their design, or mentions "grill me".
---

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Use `AskUserQuestion` to ask me questions. Ask one question at a time so each answer can inform the next.

Before asking me a question, check whether you can answer it yourself from the conversation history, files or documents on this machine, through your connectors, or the `WebSearch` tool. Only ask me questions that require human judgment, context I hold, or a design decision.

This is a good skill because every sentence does work.

The description gives the agent trigger terms. The body defines the interaction. The tool instruction changes how questions are asked. The final paragraph prevents lazy interruption and keeps the human focused on decisions.

Why this matters beyond engineering

Developers adopted skills early because their work already lived near files, commands, tests, and repos. The same pattern applies across a business.

An operator who writes the same weekly update every Friday has a skill candidate. A finance lead who runs the same variance analysis every month has a skill candidate. A team that keeps turning meeting notes into follow-ups has a skill candidate. A founder who keeps pressure-testing plans with /grill-me has a skill candidate.

At Elios, people use Claude, Codex, Claude Cowork, and other agent harnesses across shared workflows. The syntax changes. The tool names change. The durable skill-writing principles stay stable: be concise, make the trigger obvious, tell the agent what to inspect, match specificity to risk, and test against real work.

AI agent skill checklist

Before you share a skill with a team, run this checklist:

1. Name the repeated workflow. If the workflow has no name, keep using a prompt until the pattern is clearer.
2. Write a specific third-person description. Include the task, the trigger, and likely user language.
3. Delete no-ops. Remove anything that asks for generic competence.
4. Set the freedom level. Use loose guidance for judgment-heavy work and exact steps for fragile work.
5. Use one-level references. Keep SKILL.md lean and put durable detail nearby.
6. Add a workflow or feedback loop. Write the sequence when order, validation, or stopping conditions matter.
7. Test with a fresh agent. Revise based on observed behavior.

The right skill should feel almost too short. That is usually a sign that the remaining words are doing work.

Turn repeated AI work into infrastructure

The teams that get real value from agents will turn repeated work into reusable behavior.

Skills are one of the simplest ways to do that. They capture the workflows your best people already use and make them available to everyone working with an agent.

Look for the repeated tasks first: the recurring report, the plan critique, the client prep, the search workflow, the review checklist, the decision tree. Then write the smallest skill that changes what the agent does.

Give us one problem. Let us prove it.