how to write an ai skill

A skill is a document that teaches an AI one job. Writing one takes an hour. Writing one that the AI actually loads at the right moment and follows correctly takes a little more thought, almost all of it before you start typing.

1. pick one job

The most common mistake is a skill that tries to be a whole role: "marketing", "backend", "writing". A skill works best when it covers one job with a recognisable start and end: write the weekly report, review a database migration, turn interview notes into a persona.

A useful test: can you name the moment someone would reach for it? If the answer is "whenever they're doing marketing", split it.

Good candidates are jobs you do repeatedly, with variations, where the quality depends on knowing how you do it.

2. write the description first

The description is not a summary for humans. It is what the AI reads to decide whether to open the skill at all. Every other line is wasted if this one is vague.

Say what it does and when to use it, in the words the request will actually use:

Too vague: helps with database stuff. Better: review a postgres migration before it runs. use when someone shares a migration file, asks whether a schema change is safe, or is about to alter a table in production.

Include the phrasings people really type. If someone would say "is this safe to run", put those words in.

3. write instructions, not an essay

Write imperatively, in the order the job happens.

Steps for the process. Numbered, one action each.

Rules with their reasons. "Never drop a column in the same migration that stops writing to it, because a rollback then loses data." A rule without a reason gets misapplied at the first edge case; the reason lets the model handle cases you didn't list.

The failure modes. What makes the output wrong, generic or dangerous. This list is often more useful than the list of what makes it good.

An example, when the output has a shape. One good one beats three paragraphs describing it.

A checklist at the end the AI can run against its own work before calling it done.

4. keep it one file if you can

A single file is a single link and a single thing to maintain. Move material into a second file only when the main one stops being readable in one sitting, such as a long reference table or a script, and say in the main file exactly when to open it. The AI will only read supporting files when the job calls for them.

5. separate your taste from the floor

Some of a skill is a position: a house style, a preferred order. Some is non-negotiable: correctness, safety, accessibility. Mark which is which. It lets someone adapt your skill without breaking the parts that mattered.

6. test it on real requests

Ask for the job the way you normally would, in a fresh session, without mentioning the skill. Check three things. Did the AI load it? If not, the description needs the words you used. Did it follow the steps? If not, the instructions are ambiguous somewhere. Is the output better than without it? If not, the skill is telling the model what it already knew.

the mistakes that make skills fail

• a description with no trigger, so the skill is never loaded;
• a whole role in one skill, so it's loaded for everything and useful for nothing;
• rules without reasons, so edge cases go wrong;
• the current task baked in, which is a prompt pretending to be a skill;
• private context left in, which makes it unshareable and often confusing to the model;
• no date and no author, so nobody, including you in six months, can tell if it's current.

the checklist

• one job, with a moment you can name
• a description that says what and when, in real phrasing
• steps in the order the job happens
• every rule has its reason
• the failure modes are listed
• a checklist at the end
• one file, or a clear note on when to open the others
• tested in a fresh session without naming the skill
• author, date and licence, if you'll share it

a skill to write skills

innernet keeps the skill format as a skill in its own right. Paste its link into your AI and ask it to draft a skill from a job you describe, or to check one you've written. When it's ready, how to share an ai skill covers giving it one link.

read skills people have written →

questions

how do i write a claude skill?

Create a folder named for the skill with a SKILL.md file inside. Start the file with a metadata block holding a name and a description that says what the skill does and when to use it, then write numbered steps, rules with their reasons, the common mistakes and a closing checklist. Test it by asking for the job in a fresh session without mentioning the skill.

what makes a good skill description?

It names what the skill does and the moment to use it, in the words people actually type when they need it. The AI reads only the description to decide whether to load the skill, so a vague one means the skill is never used.

how long should an ai skill be?

As short as the job allows while still covering the steps, the rules with reasons, the failure modes and a checklist. Most good skills fit in one file readable in a few minutes; move long reference material into a separate file the main one points to.

why isn't my skill being used?

Usually the description doesn't contain the words of the request. Rewrite it to say when to use the skill in the phrasing people really use, and check the skill covers one job rather than a whole area.

innernet is user-owned memory across AI tools, reachable over MCP. The skills you write live beside your projects, and every tool you connect reads them. innernet.live

Checked 17 september 2026.