Creating skills

A guide for PMs, QA engineers, designers, and anyone who doesn’t write code daily.

What is a Skill?

A skill is a set of instructions that teaches Claude how to handle a specific task or workflow. Think of it like a recipe — once written, Claude follows it every time instead of you explaining from scratch.

Skills are plain text files. No coding required.

Why Create Skills?

Without a skill	With a skill
Explain your process every conversation	Claude follows it automatically
Inconsistent results	Same quality every time
10+ messages to get it right	1-2 messages
Only you know the workflow	Whole team benefits

Real examples at AWL

Code review — Claude checks for security, bugs, and performance in parallel
Bug analysis — Claude reproduces, isolates, and suggests fixes systematically
Writing style guide — Claude follows AWL brand voice and gender-inclusive language

How to Create a Skill

Option A: Let Claude do it (recommended)

Use Anthropic’s official skill-creator plugin. It interviews you, writes the skill, tests it against example prompts, and tunes the description so the skill triggers reliably. We no longer maintain our own /create-skill command.

Install it once, inside Claude Code:

/plugin install skill-creator@claude-plugins-official

Tell Claude what you want, for example: “Create a skill that writes QA test cases from a user story.”
Claude asks questions, generates the skill, and offers to test and improve it.

The official marketplace is added automatically the first time Claude Code starts. If the install says the marketplace is missing, run /plugin marketplace add anthropics/claude-plugins-official first. Building a whole plugin (hooks, commands, agents)? The official plugin-dev plugin covers that.

Option B: Create it manually

A skill is just a folder with one file:

my-skill/
└── SKILL.md

The SKILL.md file has two parts:

1. Header (YAML frontmatter) — tells Claude when to use the skill:

---
name: my-skill-name
description: What it does. Use when someone asks to "do X", "help with Y", or mentions "Z".
---

2. Instructions (Markdown body) — tells Claude how to do the task:

# My Skill

## Steps

1. First, do this
2. Then check that
3. Finally, produce this output

## Rules

- Always include X
- Never skip Y
- If Z happens, do W instead

How to Submit Your Skill

Quick way (no git required)

Write your SKILL.md (or let Claude generate it with the skill-creator plugin)
Post it in #tools-claudecode with a short description of what it does
A developer will add it to the marketplace repo for you

Self-service (if you know git)

Clone the marketplace repo
Create a branch: git checkout -b skill/your-skill-name

Add your skill folder under the matching plugin’s skills/ directory:

Plugin	Use for
`awl-general`	Day-to-day dev & workflow skills (default)
`awl-testing`	Testing skills
`awl-cicd`	CI/CD and deployment
`awl-writing`	Writing and style guides
`awl-project-management`	PM and project workflows

Validate: node scripts/validate-marketplace.js
Commit, push, and open a Merge Request

CI auto-validates the structure and bumps the version on merge.

Writing Tips

Rules to Follow

Rule	Why
Folder name in `kebab-case` (lowercase, hyphens)	`design-review` not `Design Review`
File must be exactly `SKILL.md`	Case-sensitive — `skill.md` won’t work
No `README.md` inside the skill folder	Claude reads SKILL.md, not README
Description must say WHAT + WHEN	Claude uses this to decide when to load the skill
Keep instructions clear and numbered	Claude follows numbered steps more reliably

Writing a Good Description

The description field is the most important part. It determines whether Claude loads your skill at the right time.

Good descriptions

# Specific — says what + when
description: Reviews UI designs for accessibility compliance. Use when someone asks to "check accessibility", "audit colors", or "review for WCAG".

# Includes trigger phrases people actually say
description: Generates QA test cases from user stories. Use when someone says "write test cases", "create test plan", or pastes acceptance criteria.

Bad descriptions

# Too vague — Claude won't know when to use it
description: Helps with design stuff.

# No triggers — Claude can't match it to user requests
description: Comprehensive multi-stage testing automation framework.

Writing Good Instructions

Do:

Use numbered steps — Claude follows them in order
Be specific — “Check the contrast ratio is at least 4.5:1” not “Check contrast”
Include examples — show what good output looks like
Add rules — “Always do X”, “Never do Y”

Don’t:

Write walls of text — keep it scannable
Be vague — “validate properly” means nothing to Claude
Assume context — state everything Claude needs to know

Adding Reference Files

If your skill needs detailed background info (style guides, checklists, templates), put them in a references/ subfolder:

your-skill/
├── SKILL.md
└── references/
    ├── brand-guidelines.md
    └── checklist.md

Then reference them in SKILL.md:

Before reviewing, consult `references/brand-guidelines.md` for the current brand standards.

This keeps SKILL.md focused while giving Claude access to details when needed.

Full Example: A QA Test Case Generator

1. Create SKILL.md:

---
name: qa-test-generator
description: Generates QA test cases from user stories or acceptance criteria. Use when someone says "write test cases", "create test plan", "generate tests for this story", or pastes acceptance criteria.
---

# QA Test Case Generator

## Instructions

1. Read the user story or acceptance criteria provided
2. Identify all testable scenarios (happy path, edge cases, error cases)
3. For each scenario, generate a test case with:
   - **Title**: Short description
   - **Preconditions**: What must be true before testing
   - **Steps**: Numbered actions to perform
   - **Expected result**: What should happen
4. Group test cases by: Happy path, Edge cases, Error cases
5. Add a coverage summary at the end

## Rules

- Always include at least one edge case per acceptance criterion
- Always include at least one negative/error test case
- Use concrete example data, not placeholders
- Format as a table for easy copy-paste into test management tools

## Example Output

| #   | Title                        | Steps                                                       | Expected Result              |
| --- | ---------------------------- | ----------------------------------------------------------- | ---------------------------- |
| 1   | Login with valid credentials | 1. Enter valid email 2. Enter valid password 3. Click Login | User sees dashboard          |
| 2   | Login with wrong password    | 1. Enter valid email 2. Enter wrong password 3. Click Login | Error: "Invalid credentials" |

2. Submit it — post in #tools-claudecode or open an MR.

Testing Your Skill

After your skill is live:

Open Claude Code
Try a prompt that should trigger your skill
Try a prompt that should NOT trigger it
Check: Did Claude follow the steps? Is the output correct?

Quick debug: Ask Claude “When would you use the [skill-name] skill?” — it will quote the description back. If it sounds wrong, improve the description.

FAQ

Q: Do I need to know how to code? No. Skills are written in Markdown — the same format used in Notion, Confluence, and GitHub docs.

Q: Can I create skills for non-dev workflows? Yes. Design reviews, copywriting guidelines, meeting note templates, QA processes — anything you can describe as steps.

Q: What if my skill doesn’t trigger? Your description needs more trigger phrases. Add the exact words people use when asking for help with that task.

Q: What if my skill triggers when it shouldn’t? Make the description more specific, or add “Do NOT use for…” to exclude certain cases.

Q: Can I update a skill after it’s merged? Yes, just edit the SKILL.md and submit another MR (or post the update in Slack). Versions are bumped automatically.

Q: Where do I get help? Slack: #tools-claudecode