Create a skill

This article walks you through building a skill from scratch, using an agency house-style skill as the example. You will write SKILL.md, add supporting files, install the skill in the Claude apps and Claude Code, and test it. New to skills? Read What a skill is and when to make one first.

Before you start

1. Pick one job for the skill. “Write in our house style” is good. “Everything about marketing” is too broad.
2. Collect what you have: style guides, checklists, good examples, templates.
3. In the Claude apps, make sure code execution and file creation is switched on in your settings (look under Settings and then Capabilities). Skills need it.

Step 1: Create the folder

Create a folder named after the skill, in lowercase with hyphens:

house-style/
├── SKILL.md
├── examples.md
└── checklist.md

Only SKILL.md is required. The other files are optional.

Step 2: Write SKILL.md

SKILL.md starts with a header (YAML frontmatter) between two --- lines, followed by the instructions in plain Markdown.

---
name: house-style
description: Applies our agency house style to texts for clients or our website. Use when writing or editing blog posts, web copy, emails, proposals or social posts.
---

# House style

Follow these rules for every text you write or edit.

## Voice

- Write like a smart colleague explaining something over coffee: clear, direct, friendly.
- Address the reader as "you". Refer to the agency as "we".
- Short sentences. One idea per sentence.

## Words

- Never use: "unlock", "leverage", "seamless", "game-changer".
- Say "website", not "web presence". Say "customers", not "end users".

## Format

- Headings in sentence case.
- Write numbers one to nine in words, 10 and up in digits.

## Process

1. Identify the audience and the channel before writing.
2. Write the draft using the rules above.
3. Check the draft against checklist.md and fix anything that fails.
4. Return only the final text, unless the user asks for notes.

## Reference files

- examples.md: before-and-after examples of our voice. Read it when unsure about tone.
- checklist.md: the final check. Always use it before returning text.

Write a description that triggers

The description is what Claude reads to decide whether to use the skill. Make it do two things:

• Say what the skill does.
• Say when to use it, with the words people actually type (“blog post”, “proposal”, “web copy”).

Keep the name short (lowercase letters, numbers and hyphens) and the description to one or two sentences. The Claude apps limit how long both can be, so short is safer.

Tip: Write the instructions as if for a new colleague: concrete rules, the reason behind unusual ones, and an example or two. Vague advice like “be engaging” helps nobody.

Step 3: Add reference files

Put longer material in separate files and point to them from SKILL.md, as in the example above. Claude only opens them when needed. Good candidates are example texts, templates, checklists and glossaries. A skill can also include small scripts (for example one that checks word counts), which Claude can run.

Step 4: Let Claude help (optional)

You do not have to write everything yourself. Claude has a built-in skill for building skills, often called skill-creator. Start a chat and say something like:

Help me create a skill for our house style. I will paste our style guide
and three example texts. Ask me questions first, then produce the skill
folder as a zip I can upload.

Review the result before you use it. You know your process best.

Step 5: Install it in the Claude apps

First zip the folder. On Mac or Windows, right-click the folder and choose the compress option, or use a terminal:

zip -r house-style.zip house-style

1. Check that the zip contains the house-style folder at the top, not loose files and not a folder inside another folder.
2. In Claude, open the Skills section of your settings (currently under Customize, then Skills).
3. Use the add or upload option and choose your zip file.
4. Make sure the skill is switched on.

Step 6: Install it in Claude Code

Claude Code reads skills straight from folders, no zip needed.

Scope	Location
One project (shared with everyone who uses the repository)	.claude/skills/house-style/SKILL.md
Just you, in every project	~/.claude/skills/house-style/SKILL.md

Claude Code uses the skill when a request matches the description, or you can run it directly by typing /house-style.

Note: A project skill is a good fit for code standards. For example, an Astro architecture skill in .claude/skills/ can describe the folder structure, how pages and content collections are set up, and the checklist for adding a new section, so every session builds things the same way.

Step 7: Test it

1. Start a new chat and ask for something the skill should handle: “Write a short blog intro about our new service.”
2. Check that Claude uses the skill (the chat shows when a skill is used) and follows the rules.
3. Ask for something unrelated and check that the skill stays out of it.
4. If results are off, improve the description or instructions, upload again and retest.

Next steps

• Install and share skills
• Write a CLAUDE.md
• Install Claude Code