How to Create a Claude Code Skill From Scratch
Writing a custom Claude Skill takes less than an hour. This guide walks through every step: SKILL.md anatomy, trigger design, local testing, and publishing to GitHub.
Why Build Your Own Skill?
The skills directory has hundreds of pre-built skills for common tasks. But every team has conventions, preferences, and workflows that no pre-built skill can fully capture. Creating a custom skill is the way to encode exactly how you work — and make Claude a specialist in your specific context.
Custom skills are also the best way to onboard Claude to a new codebase. A well-written project skill contains the architectural decisions, naming conventions, testing patterns, and business domain knowledge that Claude would otherwise need you to explain from scratch in every session.
What you need
A text editor, Claude Code CLI installed, and a project directory to test in. No coding experience is required — skills are Markdown files, not code.
Anatomy of a SKILL.md File
Every skill is a single file named SKILL.md. The file has two parts: a YAML frontmatter block that contains metadata, and the Markdown body that contains the actual instructions Claude will read.
The frontmatter tells the skills registry what the skill is, who made it, and when it should activate. The body is plain Markdown — headings, bullet points, code blocks, and prose, just like any documentation file.
The SKILL.md Format
--- name: my-skill-name description: One-sentence description of what this skill does version: 1.0.0 author: your-github-username triggers: - commit message - git commit - write a commit --- # Skill Title Brief explanation of the skill's purpose. ## Rules - Rule 1: Always use imperative mood in commit messages - Rule 2: Keep the subject line under 72 characters - Rule 3: Reference issue numbers when applicable ## Format <type>(<scope>): <short description> <optional body> ## Examples Good: feat(auth): add OAuth2 login flow Good: fix(api): handle null response from payment service Bad: Updated stuff
Write Your First Skill
The best way to start is with a task you do repeatedly. Think of the last time you had to re-explain a convention to Claude. That is your first skill. Here is the process:
Create the directory structure
In your project root, create .agents/skills/my-skill-name/ and add a SKILL.md file inside it.
Write the frontmatter
Fill in the name, description, version, author, and triggers. Keep the name lowercase with hyphens.
Write the instructions
Write clear, specific rules in the body. Include examples of good and bad output. Be explicit — Claude follows instructions literally.
Test it locally
Run claude from your project directory and ask it to perform the task. Check if it follows your rules.
Testing Locally
# Install from a local directory path npx skills add ./my-local-skill # Or just copy manually — Claude loads all skills in .agents/skills/ mkdir -p .agents/skills/my-skill-name cp SKILL.md .agents/skills/my-skill-name/SKILL.md # Start Claude and verify the skill loaded claude
Once Claude starts, ask it: "What skills do you have loaded?" It should list your skill. Then test it with a prompt that matches your triggers and verify the output follows your rules.
Designing Good Triggers
The triggers field tells the skills system which prompts should activate your skill. Triggers are keyword or phrase matches. When a user's prompt contains one of your trigger phrases, Claude loads and applies your skill.
Good triggers are specific enough to activate at the right time but broad enough to catch natural language variations. For a commit message skill, good triggers include: commit message, write a commit, git commit, commit this. Avoid triggers that are too general (like write or code) — they'll activate on unrelated tasks.
"Write triggers the way a user would naturally ask for the task. If you would say 'write me a commit message', then 'commit message' is a good trigger."
Best Practices for Skill Content
Skills that work well share a few characteristics:
- Specific over general — "Use imperative mood" beats "write good commit messages"
- Examples are essential — show Claude exactly what good and bad output looks like
- One skill, one task — a skill for commit messages should not also cover PR descriptions
- Use headings — break the skill into sections (Rules, Format, Examples, Anti-patterns)
- Test with edge cases — ask Claude to do the task in unusual situations to check for gaps
Publishing to GitHub
Publishing a skill is just pushing a GitHub repository with your skill's folder at the root. The repository name becomes the skill's identifier. A skill at github.com/your-username/smart-git-commit installs with npx skills add your-username/smart-git-commit.
# Create a new GitHub repo with your skill # Repository structure: # your-skill-name/ # ├── SKILL.md (required) # ├── README.md (recommended) # └── CHANGELOG.md (optional) git init git add SKILL.md README.md git commit -m "feat: initial skill release v1.0.0" git remote add origin git@github.com:your-username/your-skill-name.git git push -u origin main
Submit to the Directory
Once your skill is published and tested, you can submit it to the Claude Skills Hub directory for community discovery. Use the SKILL.md Generator to validate your skill's format, then submit it here. Published skills appear in the skills directory after editorial review.