AI Skills: What They Are, How to Write Them, and Where They Fit

Most people try to improve their AI results by writing longer prompts.

That can help once.

But if you do the same kind of work every week, there is a better place for those instructions: an AI skill.

A skill turns a good set of instructions into a small, reusable package. You can use it to write blog posts, review a spreadsheet, prepare meeting notes, or guide a coding agent through a project. Write it once, then stop rebuilding the same process in every chat.

This guide explains what skills are, how to write one, and how they work in tools such as Claude and OpenCode.

What is an AI skill?

An AI skill is a folder containing instructions for a repeatable job. The required file is called SKILL.md. It usually has two parts:

YAML frontmatter that gives the skill a name and description.
Markdown instructions that explain how the agent should do the work.

A skill can also include scripts, reference documents, templates, and other resources. The Agent Skills specification defines the basic format.

Think of a skill as a recipe card for an AI agent. A prompt says, "Do this now." A skill says, "When this kind of job comes up, use this process and meet these standards."

That difference matters when the work has several steps. A blog-writing skill can remember to clarify the audience, build an outline, check factual claims, and edit the final draft. You do not need to remember that checklist each time.

What a skill is not

A skill is not a new AI model. It does not make Claude or an OpenCode agent smarter by itself.

It is also not a magic automation button. The skill provides the method. The agent still needs access to the files, tools, services, and permissions that the job requires.

And it is not just a huge prompt copied into a folder. A useful skill tells the agent when to use it, what to do, what to return, and what to do when the inputs are incomplete.

Why write a skill?

Write one when you notice a pattern such as:

You keep pasting the same instructions into different chats.
You follow the same checklist for every client or document.
You want two different AI tools to follow the same house style.
You need an agent to handle a workflow in the same order every time.
You want a process that a teammate can inspect and improve.

The payoff is not only speed. A written skill makes your process visible. You can see what the agent is being told to do, change one step, and test the result again.

How to write an AI skill

1. Start with one repeatable job

Do not begin with "make the AI better." Pick a job with a clear beginning and end.

Good first skills include:

Draft a blog post from a topic and a few notes.
Turn a transcript into decisions and action items.
Review a pull request for bugs and missing tests.
Clean a spreadsheet without changing its existing layout.
Prepare a client brief from notes and public research.

The narrower the first version, the easier it is to tell whether it worked.

2. Give it a clear name and description

The name should say what the skill does. The description should say what it does and when to use it. Agents use that description when deciding which skill fits a request.

The name also needs to match the skill directory. For example:

blog-post/
└── SKILL.md

The Agent Skills specification requires the name to use lowercase letters, numbers, and single hyphens. The description must be present and should include useful trigger words.

3. Write the process in plain language

Tell the agent what to do in the order that matters. Explain decisions that a new person joining the workflow would need to understand.

Avoid vague instructions such as:

Make the post engaging and high quality.

Try this instead:

Start with the reader's problem. Use one concrete example. Keep the opening
short. Before drafting, ask for any missing audience or product details.

The second version gives the agent something it can act on.

4. Define the output

Say what the final result should contain. Include the format, length, tone, and any parts that must not be skipped.

For a blog-writing skill, that might mean:

A clear title and opening hook.
Short sections with useful headings.
Examples that a beginner can follow.
An FAQ section for common objections.
Links to primary sources for technical claims.
No invented statistics, quotes, or customer stories.

Do not make every instruction a hard rule. Leave room for judgment where the work needs it.

5. Cover the awkward cases

Most weak skills describe the happy path and ignore everything else.

Add instructions for missing information, bad input, conflicting requests, and tasks that are outside the skill's purpose. A good skill can say, "Ask one short question before drafting if the intended audience is unknown." It can also say, "Do not invent a source. Mark the claim for review instead."

6. Test it with real requests

Use three or four requests that resemble the work you actually do. Include one easy case, one incomplete case, and one case that should not trigger the skill.

Look for practical failures:

Did the agent choose the skill at the right time?
Did it follow every important step?
Did it ask for missing information instead of guessing?
Is the output useful without a second round of cleanup?

Then edit the description or instructions. Skills get better through this small test-and-revise loop, not through one giant first draft.

A small example: a blog post skill

Here is a starting point for a skill that helps with blog posts:

---
name: blog-post
description: Draft clear, useful blog posts from a topic and source notes. Use when planning, writing, or revising an educational article.
---

When writing a blog post:

1. Ask who the reader is and what they should be able to do afterward.
2. If the topic involves current facts, ask for sources or research them first.
3. Lead with the reader's problem, not a generic introduction.
4. Build a short outline before writing the full article.
5. Use concrete examples and explain technical terms on first use.
6. Mark unsupported claims instead of inventing details.
7. End when the article has answered the reader's question. Do not repeat the introduction.

This is deliberately small. It gives an agent a useful default without trying to dictate every sentence.

Use case: writing a better blog post

A writing workflow often needs more than one pass. One skill can handle the article structure. Another can check facts. A third can edit the language.

For example:

Use a research or outline skill to collect the reader's questions.
Use a blog-writing skill to turn the material into a draft.
Use a fact-checking skill to verify names, dates, numbers, and product details.
Use a humanizing or editing skill to remove stiff phrasing and repeated ideas.
Read the final version yourself before publishing it.

This is a useful boundary: the agent can help with research and editing, but a skill should not pretend that a source was checked when it was not.

Use case: automating a workflow

The same idea works outside writing.

Imagine a weekly meeting workflow. The skill could tell the agent to read the transcript, separate decisions from discussion, assign each action to a named owner, include due dates only when they were actually stated, and flag anything unclear.

A client-research skill could gather information from approved sources, keep facts separate from guesses, and produce a brief in a fixed format. A spreadsheet skill could inspect the workbook first, preserve its existing style, and check for formula errors before returning the file.

The key question is simple: do you do this more than once, and would a clear checklist make the result more reliable? If yes, it may be a good skill.

What are AI coding agents?

An AI coding agent is a tool that combines a language model with access to a working environment. Depending on the tool and its permissions, it can inspect files, edit code, run commands, execute tests, and explain the changes.

That is different from a chat window that only returns text. A coding agent can work through a task in the repository while keeping the instructions and the current files in view.

Skills give that agent a repeatable way to work. A code-review skill might tell it to check behavior before style, report findings with file and line references, and avoid changing code during the review. A release skill might provide a checklist for tests, version changes, notes, and the final command.

A skill does not remove the need to review the agent's work. It gives the agent a better process to follow.

Claude and OpenCode

Claude

Claude has more than one way to use skills, so it helps to name the product.

In Claude Code, a skill is placed in a project .claude/skills/<name>/SKILL.md directory or in the personal ~/.claude/skills/<name>/SKILL.md directory. Claude Code can choose a matching skill automatically, and you can invoke one directly with /skill-name. The Claude Code skills documentation describes the supported locations and frontmatter.

Claude's web and desktop experiences use uploaded skills rather than the local filesystem. The project OpenCode and Claude Skills website provides the collection and a ZIP download of all skills. That download is the whole repository. Extract it first, then upload the individual skill folder or a ZIP whose top level contains that skill's SKILL.md file.

OpenCode

OpenCode discovers skills from project .opencode/skills/<name>/SKILL.md and global ~/.config/opencode/skills/<name>/SKILL.md directories. It also supports the compatible .claude/skills/ and .agents/skills/ locations.

OpenCode lists available skills for the agent and loads a skill on demand with its native skill tool. You can ask for a task normally and let it select the right skill, or mention the skill by name in your request. See the OpenCode Agent Skills documentation for discovery and permission settings.

Because both tools use the SKILL.md pattern, a well-written basic skill can often be moved between them. Tool-specific features and permissions still need to be checked. Keep the core instructions portable unless you have a reason to depend on one platform.

FAQ

Do I need to know how to code?

No. A skill is mainly a text file. If you can write a clear checklist, you can write a first skill. Scripts and supporting files are optional.

Is a skill the same as a prompt?

They are related, but they serve different moments. A prompt is a request for a particular turn. A skill is a reusable procedure that can be selected whenever the same type of request appears.

Should I put these instructions in a system prompt or project rules file?

Use a general rules file for facts and conventions that should apply all the time. Use a skill for a process that should load only when the task calls for it. This keeps unrelated work from receiving a long checklist.

Can a skill automate everything by itself?

No. It can describe the steps, but the agent needs the right tools and access. A skill that says "send the email" cannot send anything if the agent has no mail tool or permission to use it.

Why does the agent ignore my skill?

Check the basics first. The file must be named exactly SKILL.md. The directory name and frontmatter name should match. The description should include the kind of request that should trigger the skill. In OpenCode, also check skill permissions. In Claude Code, check that the skill is in a directory Claude Code actually scans.

Can one skill use another skill?

That depends on the agent. Do not assume that a reference to another skill will load it. If a workflow needs several stages, either ask the agent to use each stage explicitly or write the important handoff rules into the main skill.

How long should a skill be?

Long enough to remove ambiguity, but short enough that the main instructions stay easy to follow. Put detailed material in reference files when it is only needed for some tasks. The Agent Skills specification recommends progressive disclosure: metadata first, instructions when activated, and extra resources only when needed.

What is the best first skill to write?

Pick the task you have explained to an AI at least three times. You already have the raw material. Write down the steps, add the edge cases you keep correcting, then test it on a real example.

The short version

An AI skill is a reusable instruction package for an AI agent. It gives a repeatable job a name, a trigger, a process, and a definition of done.

Start with one workflow. Keep the first version small. Test it against real work. Add rules when you find a failure.

That is how a prompt becomes part of a system instead of disappearing in an old chat thread.