How to Create an AI Skill

To create an AI skill, pick one job you repeat and write down its inputs, steps and output. Say what the AI should do when information is missing, and write a short description that tells it when to use the skill. Save it as a SKILL.md file, test it with three cases, and fix whichever part caused a failure.

A skill is a job card for your AI. A new starter given a vague job card guesses; one given a clear card does the job your way. The same is true of an AI. A useful skill has seven parts:

• One job. A skill that writes proposals shouldn't also chase invoices.
• A description that tells the AI when to use the skill, in the words people actually use.
• Inputs, including which ones the AI must never guess, such as prices, dates and names.
• Steps and decisions, including what to do when sources conflict or something is missing.
• An output with named sections, a length and a reader in mind.
• Pointers to supporting material, such as the template and price list, rather than copies of them.
• Checks the AI runs before it says the work is finished.

Focus pays off. A narrow skill is easier to test, easier to fix and less likely to pick up requests it wasn't written for.

Choose one job. Write one sentence that names the task and its result, such as "Turn discovery meeting notes into a first-draft proposal with scope, pricing and next steps." If the sentence needs an "and also", you probably have two skills.

List the inputs. Name the source material and the decisions the AI must not make up. If the notes don't give a quantity or a date, the skill should ask or mark the gap. It should never invent a value to complete the format.

Describe the output. Name each section and what goes in it. Say how long it should be and who reads it. A reviewer should be able to tell at a glance whether the result meets the brief.

Write the steps and decisions. Keep the steps short. Spend your words on the judgement calls: what counts as agreed, how to handle two conflicting notes, when to stop and ask.

Point to supporting material. Templates, rate cards and past examples change more often than the method. Keep them in your knowledge base and name them in the skill, so updating a price list doesn't mean rewriting the skill. If the job already has an SOP, How to Turn an SOP Into an AI Skill shows how to build the skill around it.

Add the checks. End with a short list the AI runs before finishing, such as "every price matches the rate card".

Write the description last. The description is how the AI decides whether to use the skill, so lead with the main use and the words people type. OpenAI's guidance says to front-load the key use case and trigger words (OpenAI: Build skills). The open standard allows up to 1,024 characters (Agent Skills specification), but Claude's custom skill guide sets 200 (Anthropic: How to create custom skills), so keep it short.

Riverstone Electrical, a fictional contractor, quotes commercial fit-outs. Each estimator writes proposals differently, and prices sometimes go out that aren't on the current rate card. Their first skill looks like this:

• Name: commercial-proposal
• Description: Drafts a commercial fit-out proposal from discovery notes, using the proposal template and current rate card. Use when asked for a proposal, quote document or pricing summary.
• Inputs: discovery notes, the client's name and site address, the rate card and the proposal template.
• Steps: summarise the client's goals, list the scope items, price each item from the rate card and set out next steps.
• Decisions: if the notes don't give a floor area, ask for it. Never estimate a price that isn't on the rate card. Mark anything the client hasn't confirmed as "to confirm".
• Output: summary, scope, pricing table, assumptions and next steps, in under two pages.
• Checks: every price matches the rate card, every scope item appears in the notes and each next step has an owner.

The first test showed the AI adding a "contingency" line nobody asked for. The fix was one sentence: "Only include line items from the notes or the rate card." The second test passed.

• Pick a job you do at least weekly, with a result you can judge.
• Write the one-sentence task and result.
• List the inputs and mark the ones the AI must never guess.
• Name the output sections and the reader.
• Write the decisions for missing or conflicting information.
• Name the templates and reference documents the skill should use.
• Add three to five checks for the end of the job.
• Write the description last, then save the skill as a folder containing SKILL.md.
• Or open the skill builder, describe the task, answer its questions and download the result.

• A normal request. Use a real, complete example. Check every fact against the source, not just the tone.
• Incomplete input. Remove one critical detail, such as the floor area. The skill should ask or flag it, not fill it in.
• An unrelated request. Ask for something close but different, such as an invoice. The skill shouldn't trigger. If it does, narrow the description.

If you use more than one AI tool, run the same three cases in each.

When a test fails, find the instruction that was missing or unclear and change only that. Run the same examples again and compare. Asking an AI to "improve" a whole skill tends to make it longer and vaguer until it stops working. Keep the earlier version so you can go back to it. Once a skill works, you can link it with others into a workflow.

A skill tells your AI what to do. Your knowledge base shows it how, in detail. Your company context tells it who it's for. The Contexta harness brings them together, in every AI.

With Contexta, your skill doesn't need to repeat who your company is. Company context, covering your terminology, naming and formats, sits under every skill, set for the company and adjusted for each team. The rate card, template and past proposals stay in your knowledge base, in your own SharePoint or Google Drive, and the skill points to them. Spaces give the estimating team its own home and rules.

New versions stay in draft until you publish them. Version history shows who changed what and when, and you can compare with the current version and restore in one step. Connected AIs fetch the published version on next use, while a downloaded copy stays as it was. See Product for the details.