How to Create a Claude Skill

1. Choose one recurring job

Start with the work, not the format. A good skill candidate is a task you can name in one sentence, repeat across projects, and judge with a recognizable definition of done. "Create investor-ready board deck charts from this spreadsheet" is a candidate. "Help with business" is not.

Write the non-goals beside the goal. If the skill writes launch copy, say whether it should also generate images, post to social media, or inspect analytics. Clear exclusions improve both safety and trigger accuracy.

2. Write the trigger description

The description field does double duty: it tells humans what the skill is for and gives the agent a matching rule. Include the task, the domain, and the signal that should cause activation. Leave out grand claims, adjectives, and implementation details that do not help matching.

---
name: invoice-audit
description: Use when reviewing vendor invoices against contract terms, purchase orders, and known exception rules.
---

If you cannot write a specific description, the skill is probably not scoped tightly enough.

3. Write the procedure

Use imperative steps. Tell the agent what to inspect first, which files to open, which assumptions to avoid, and what output shape to produce. Give examples only when they remove ambiguity. For complicated tasks, route to a reference file instead of overloading the entrypoint.

Strong procedures include stop conditions. A skill that might touch credentials, legal claims, medical advice, external deploys, or customer data should tell the agent when to ask for confirmation or perform a read-only review.

4. Package references, scripts, and assets

Add files because they reduce error. If the agent needs a current schema, put the schema in the skill. If the job needs a parser, put a script in scripts/. If the output must match a format, include a template in assets/.

Every bundled file should have a reason to exist. If a reference file duplicates the same instruction in three places, cut it down. If a script makes a network call or writes to disk, document that behavior in SKILL.md so reviewers can spot it quickly.

5. Evaluate before sharing

Test positive prompts, near-miss prompts, and adversarial prompts. A positive prompt should trigger the skill. A near-miss prompt should not. An adversarial prompt should not make the skill ignore its own safety boundaries.

Keep a small eval log next to the skill while it is young. The log does not need a full framework on day one; a table of prompt, expected behavior, actual behavior, and fix is enough to improve the description and instructions.

FAQ