Skill patterns and best practices
Common patterns, anti-patterns, and habits of great skill builders
⏱ Est. ~8 min
01 · Read
Now that you know how skills work, let's look at the patterns developers actually use every day.
The most popular skills fall into a few categories: - Code style — enforce naming conventions, formatting rules, structural patterns - Code review — consistent checklists for reviewing PRs and code changes - Commit messages — enforce formats like Conventional Commits - Testing — match your project's testing framework and patterns - Documentation — standardize how docs, comments, and READMEs are written
Each pattern follows the same structure: clear rules, concrete examples, explicit output format. Let's look at two of the most useful.
Key points
- Code-style skills enforce naming, formatting, and structural conventions
- Review skills provide consistent code review checklists
- Commit message skills enforce formats like Conventional Commits
- Testing skills match your project's existing test patterns
- Documentation skills standardize how docs are written
02 · Code example
Here's a skill that enforces all commit messages use Conventional Commits format.
commit-style/SKILL.md
---
name: Commit Message Style
description: Enforces Conventional Commits format
instructions: Use when creating git commits
---
## Format
All commits must follow Conventional Commits:
```
<type>(<scope>): <description>
[optional body]
```
## Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `refactor`: Code change that neither fixes nor adds
- `test`: Adding or updating tests
- `chore`: Maintenance (dependencies, CI, build)
## Rules
- Description must be lowercase, no period at the end
- Scope is optional but encouraged
- Body should explain WHY, not WHAT (the diff shows what)
- Max 72 characters for the first line
## Examples
Good: `feat(auth): add password reset flow`
Good: `fix(api): handle null response from payment gateway`
Bad: `Fixed stuff`
Bad: `Update code`
Look how explicit this is — exact format, enumerated types, character limit, examples of good and bad. The more specific your rules, the more consistent Claude's commits are. Vague instructions like "write good commit messages" don't work.
03 · Code example
Here's a skill that tells Claude to match your project's existing testing conventions.
test-writer/SKILL.md
---
name: Test Writer
description: Writes tests matching project conventions
instructions: Use when writing or updating tests
---
## Conventions
- Use `describe` / `it` blocks (not `test`)
- Test file goes next to source: `Foo.ts` → `Foo.test.ts`
- Use `vi.fn()` for mocks (Vitest, not Jest)
- Arrange-Act-Assert pattern in every test
## What To Test
- Happy path first
- Error cases and edge cases
- Boundary values (0, 1, -1, empty string, null)
- Never test implementation details — test behavior
## Naming
`it('should return 404 when user not found')`
Not: `it('test user')`
This skill cites the project's specific testing framework (Vitest) and patterns (describe/it, vi.fn). Generic "write good tests" instructions don't help — Claude is already trying to write good tests. This skill tells it your specific conventions.
04 · Quiz
Remember: skills should add rules Claude wouldn't know on its own. Which of these instructions is specific enough to actually change Claude's behavior?
- Be a helpful assistant who writes good code
- When writing API endpoints, return JSON with camelCase keys, use kebab-case URLs, and use error codes from our error-codes.ts file
- Always use best practices when writing code
- Write code like a senior engineer
05 · Drag to sort
Think about what makes the biggest difference to skill quality. A vague skill without examples is worse than a concrete one — sort these practices from most to least impactful.
(This section is interactive — please enable JavaScript.)
06 · Read
Some skills actually make Claude worse. Here's what to avoid: Too vague: "Write good, clean code." Claude is already trying. Your skill should add specific rules Claude wouldn't know on its own.
Too long: A 500-line skill with rules for every possible situation overwhelms Claude's context. Keep skills focused on one workflow. Multiple focused skills beat one giant one.
Duplicating built-in behavior: Claude already knows how to format code, write markdown, use git. Don't waste skill space on things Claude does well by default.
Contradictory rules: "Always add comments" + "keep code minimal" creates confusion. Check your rules for internal conflicts before testing.
Key points
- Don't write vague skills — be explicit or don't write it
- Don't write giant skills — one skill, one focused workflow
- Don't duplicate what Claude already does well by default
- Check for contradictory rules within a skill
07 · Read
You now have a superpower most Claude Code users don't know about: the ability to teach Claude exactly how you work.
Every team has conventions. Every developer has preferences. Skills turn those unspoken rules into permanent, shareable, version-controlled instructions.
Start small. Pick the one thing you tell Claude most often and turn it into a skill. Test, refine, commit. Then add another. Over time, your collection of skills becomes a force multiplier — every skill you write makes Claude better at your specific work.
The difference between a generic AI assistant and a personalized AI workflow? Skills.
Key points
- Start with one skill for your most-repeated instruction
- Iterate: test, refine, commit
- Share project skills via git so the whole team benefits
- Build a collection over time — each skill makes Claude smarter about your work
- Skills are the difference between a generic AI assistant and a personalized AI workflow
08 · Quiz
You wrote a skill that says "write good, clean code." After testing, Claude's output doesn't seem any different. Why?
- The SKILL.md file has a syntax error
- Skills only work with the Opus model
- The instruction is too vague — Claude is already trying to write good code
- You need to restart Claude Code after adding skills
09 · Fill in the blank
A 500-line skill covering every possible situation is an anti-pattern. You should write multiple _____ skills, each covering one workflow.
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.