How to Create Claude Skills: Build, Install and Test Your First Skill

A developer published a step-by-step guide to creating Claude Skills, walking through the required SKILL.md file with YAML frontmatter (name capped at 64 characters, description at 200), optional scripts for deterministic operations, and installation paths for Claude.ai, the desktop app, and Claude Code. The walkthrough uses a Code Review Skill enforcing TypeScript, JavaScript, and Python standards as its example, and recommends testing by running the skill in a fresh session with it disabled to compare outputs.

Here is how to create Claude Skills, from the first SKILL.md to installing the skill in Claude.ai or Claude Code and testing that it triggers. In Part 1 of this series https://nulltensor.com/posts/claude-skills-might-be-bigger-than/?utm source=devto&utm medium=crosspost&utm campaign=claude-skills-might-be-bigger-than - “An Intro to Claude Skills and How It’s Different” - we covered the fundamentals: What Claude Skills are and how progressive disclosure works The critical differences between Skills, Projects, MCP, and Custom Instructions A decision framework for when to use each tool Why Skills represent a fundamental shift in AI customization If you haven’t read Part 1 yet, I highly recommend starting there to understand the concepts we’ll be building on. Now that you understand what Skills are and why they matter, it’s time to get hands-on. In this guide, we’ll actually build Skills together, explore real-world use cases, and give you the practical knowledge to start creating your own AI expertise library. What we’ll cover in this post: Creating your first Skill step-by-step Code Review Skill example Adding executable scripts for deterministic operations Real-world Skills I use as a CTO Industry examples from companies using Skills in production Advanced patterns and best practices Common pitfalls and debugging strategies Your week-by-week action plan Let’s build. If you only want the steps, here they are. The rest of the guide explains each one. Create a folder named after the skill, for example code-review/ . In Claude Code the folder name becomes the command name. Inside it, create SKILL.md . Start with YAML frontmatter containing a name 64 characters maximum and a description 200 characters maximum . Claude reads the description to decide when to load the skill, so write it as the situations that should trigger it, not as a slogan. Below the frontmatter, write the instructions in Markdown: when to use the skill, the standards to apply, and the output format. Put long reference material in separate files in the same folder and link to them from SKILL.md , so Claude loads them only when needed. Add scripts under scripts/ if a step needs a deterministic result, such as a complexity check. Install it. Where you put the folder depends on which Claude you are using: Claude.ai and the desktop app: zip the folder the skill folder must be the root of the zip , upload it, then enable it under Customize, then Skills . Claude Code: no upload. Save the folder as .claude/skills/code-review/ inside the repository for a project skill, or ~/.claude/skills/code-review/ for a personal skill available in every project. /code-review . Then try a fresh session with the skill disabled and compare the two outputs. If the skill did not help, the instructions need work. Now, the full walk-through. Let’s build something real. I’ll show you how to create a “Code Review Skill” that enforces your team’s standards. Every skill needs just one required file: SKILL.md Here’s the basic structure: --- name: code-review description: Review code following team standards, catching common issues and suggesting improvements --- Code Review Skill When to Use This Skill Activate this skill when the user asks to: - Review code for quality, security, or performance - Check pull requests - Identify anti-patterns or bugs - Suggest code improvements Our Code Standards TypeScript/JavaScript - Use explicit return types for functions - Prefer const over let, never use var - Use meaningful variable names no single letters except loop counters - Max function length: 50 lines - Max file length: 300 lines Python - Follow PEP 8 strictly - Use type hints for function signatures - Docstrings required for all public functions - Max function complexity: 10 McCabe General Principles - DRY: Don’t Repeat Yourself - Single Responsibility: Each function does one thing - Boy Scout Rule: Leave code better than you found it Common Anti-Patterns to Flag 1. God Objects : Classes that do too much 2. Magic Numbers : Unexplained constants 3. Premature Optimization : Over-engineering simple solutions 4. Callback Hell : Deeply nested callbacks use async/await 5. Swallowed Exceptions : Empty catch blocks Review Checklist For each code review, check: - Code follows language-specific standards above - Functions have clear, single purposes - No obvious security issues SQL injection, XSS, etc. - Error handling is appropriate - Tests would be easy to write for this code - Code is self-documenting or has necessary comments Output Format Structure your review as: Summary : Brief overview 2-3 sentences Critical Issues : Security or correctness problems if any Improvements : Specific suggestions with line numbers Positive Notes : What’s done well always include this Priority : High/Medium/Low for addressing the issues Examples Good Review Example Summary : Clean implementation of user authentication with proper validation and error handling. Critical Issues : None Improvements : - Line 45: Consider extracting email validation to a separate utility - Line 78: Add rate limiting to prevent brute force attacks Positive Notes : Excellent use of TypeScript types, clear separation of concerns, good test coverage. Priority : Medium suggestions are enhancements, not blockers Method 1: Manual Creation in Claude.ai Create a folder: code-review/ . The folder name should match the name in the frontmatter. Inside it, create SKILL.md with the content above Zip the folder so that the skill folder is the root of the archive, not nested inside another folder In Claude.ai, upload the zip and enable the skill under Customize, then Skills . Anthropic's custom skills guide https://support.claude.com/en/articles/12512198-how-to-create-custom-skills has the current screenshots; this menu has moved once already since Skills launched. Skills need code execution enabled in your Claude.ai settings. If the upload option is missing, check that first. Method 1b: Manual Creation in Claude Code Claude Code reads skills from disk, so there is nothing to upload: Create .claude/skills/code-review/SKILL.md in the repository project skill, shared with everyone who clones it or ~/.claude/skills/code-review/SKILL.md personal skill, every project on your machine Start a session and type /code-review to run it directly, or ask for a review and let Claude pick it up from the description The frontmatter format is the same, so one folder can serve both. The Claude Code skills reference https://code.claude.com/docs/en/skills lists extra frontmatter fields that only apply there, such as pre-approving tools. Method 2: Use the skill-creator Skill Recommended This is meta, but it works brilliantly. The skill-creator https://github.com/anthropics/skills/tree/main/skills/skill-creator is a pre-installed Skill that helps you create new Skills: In Claude.ai, enable the “skill-creator” skill it’s pre-installed Say: “I want to create a code review skill” Claude will interview you about your requirements It generates the folder structure and SKILL.md file It even bundles resources you might need The skill-creator asks questions like: “What’s the primary purpose of this skill?” “What specific workflows should it support?” “Do you need any executable scripts?” “What format should outputs follow?” Then it creates everything for you. It’s like using an AI to teach an AI how to help you better. Skills can include scripts for deterministic operations. Here’s an example for the code review skill: Create code-review-skill/scripts/complexity checker.py : python /usr/bin/env python3 “”“ Check code complexity metrics “”“ import sys import ast def calculate complexity code: str - dict: “”“Calculate McCabe complexity and other metrics”“” try: tree = ast.parse code stats = { ‘functions’: 0, ‘classes’: 0, ‘lines’: len code.split ’\n’ , ‘complexity’: 0 } for node in ast.walk tree : if isinstance node, ast.FunctionDef : stats ’functions’ += 1 Simple complexity: count decision points complexity = 1 Base complexity for subnode in ast.walk node : if isinstance subnode, ast.If, ast.While, ast.For, ast.ExceptHandler, ast.With : complexity += 1 stats ’complexity’ = max stats ’complexity’ , complexity elif isinstance node, ast.ClassDef : stats ’classes’ += 1 return stats except Exception as e: return {’error’: str e } if name == ‘ main ’: if len sys.argv < 2: print ”Usage: complexity checker.py <file path ” sys.exit 1 with open sys.argv 1 , ‘r’ as f: code = f.read results = calculate complexity code print f”Functions: {results.get ’functions’, 0 }” print f”Classes: {results.get ’classes’, 0 }” print f”Lines: {results.get ’lines’, 0 }” print f”Max Complexity: {results.get ’complexity’, 0 }” Update your SKILL.md to reference it: Tools Available This skill includes a complexity checker script. Claude can run: python scripts/complexity checker.py <file path to get objective complexity metrics before reviewing. Now Claude can automatically run complexity analysis without you asking, and without loading the entire script into context. The most common problem with a first skill is that it never activates. Work through these in order: Is it enabled? In Claude.ai, check Customize, then Skills. In Claude Code, check the folder path and that the file is named exactly SKILL.md . Does the description match how you ask? Claude only sees the description until it decides to load the skill. A description that says “Review code following team standards” will not fire for “look at this PR”. Add the phrasings you actually use. Is the frontmatter valid? A missing closing --- or a description over 200 characters is enough to break loading. Force it once. In Claude Code, invoke the skill with /code-review to confirm the instructions work when loaded. If the output is right, the problem is activation, not content, and the fix is the description. Let me share some Skills I’ve built and how they’ve changed my workflow: Problem : Every time I designed a new system, I’d have to remember our documentation template, what diagrams to include, what sections to cover. Solution : Created a skill that knows: Our architecture doc template intro, requirements, constraints, options, decision, consequences When to create sequence diagrams vs. architecture diagrams How to document trade-offs in our style Our specific Mermaid diagram conventions Impact : Architecture docs that used to take 2 hours now take 30 minutes, and they’re consistently formatted. Problem : Creating Jira tickets with proper structure, acceptance criteria, and labels was tedious. Solution : Skill that encodes: Our ticket template title format, description structure, acceptance criteria format Team conventions when to add specific labels, how to estimate points Links to related documentation A script to validate ticket structure before creation Impact : Combined with MCP Jira connection , I can now say “create tickets for this feature” and get properly structured, ready-to-assign tickets. Problem : Needed consistency across interviewers for technical evaluations. Solution : Skill containing: Interview question bank by difficulty Evaluation rubric Follow-up questions based on candidate responses How to give hints without giving away answers Note-taking template Impact : All interviewers now use the same framework, making candidate comparisons fair and feedback consistent. Some real implementations from companies using Skills: Rakuten E-commerce Giant Created Skills for management accounting workflows Automated finance operations that previously required manual coordination across departments Result: Streamlined workflows, reduced processing time Box Enterprise Content Management Skills that transform stored files into presentations, spreadsheets, and Word documents All outputs follow organizational standards automatically Result: Hours saved on document creation, consistent branding Financial Services Firms Skills for Discounted Cash Flow DCF modeling Comparable company analysis Due diligence workflows Initiating coverage reports Result: Junior analyst work automated, consistent methodologies Here’s how to dive into Skills effectively: Enable Skills in Claude.ai under Customize, then Skills Try the document creation skills https://github.com/anthropics/skills/tree/main/skills docx, pptx, xlsx, pdf Ask Claude to create a simple document to see Skills in action Note: You’ll see Skills mentioned in Claude’s “thinking” as it works Ask yourself: What task do I repeat weekly that has specific rules? What workflow requires consistency across my team? What knowledge do I keep having to explain to Claude? Good first Skills: Email response templates for common scenarios Report generation following your format Code scaffolding for your tech stack Meeting note structuring Use the skill-creator skill to build your first custom skill Test it thoroughly with variations of your typical requests Refine the instructions based on what Claude misses Share with a colleague for feedback Create a complementary skill Test how they work together automatically Document what worked/didn’t work Plan your next 3 skills Wrong : “General writing skill” that covers emails, blogs, tweets, documentation, and reports Right : Separate skills for each content type with specific guidelines Why : Broad skills defeat the purpose of progressive disclosure. Claude loads the whole skill when any writing task comes up. Problem : Your skill works for the happy path but fails when things get weird Solution : Test with incomplete inputs Try contradictory requirements See what happens when users ask questions the skill doesn’t anticipate Problem : Including your entire company handbook in a single skill Remember Claude only loads what it needs, but massive skills take longer to parse Break large knowledge bases into focused skills Use links to external docs for reference rather than including everything Problem : Creating skills and never updating them as processes change Version your skills add version info to YAML frontmatter Set quarterly reviews Track when skills give outdated advice Update promptly when processes change Once you’re comfortable with basic Skills, here are some advanced patterns: Create skills that naturally work together: data-extraction skill → pulls data from sources data-analysis skill → analyzes extracted data report-generation skill → formats analysis into reports Claude automatically chains them when you say “analyze this data and create a report.” Use clear conditionals in your skill instructions: Decision Logic If the user is asking about production issues: - Load emergency response procedures - Include on-call rotation information - Flag the urgency level If the user is asking about development: - Load coding standards - Reference architecture docs - Suggest testing approaches Start simple, evolve based on usage: Version 1 : Basic instructions and examples\ Version 2 : Add common edge cases you discovered\ Version 3 : Include executable scripts for repeated computations\ Version 4 : Add links to related skills for complex workflows Track version history in your SKILL.md: --- name: my-skill description: Does something useful version: 1.2.0 last updated: 2025-11-02 --- Changelog - v1.2.0: Added script for automated validation - v1.1.0: Expanded examples based on user feedback - v1.0.0: Initial release Before writing a skill, describe what you want in a normal conversation with Claude. Refine it over several chats. Once you have wording that works consistently, turn that into a skill. When Claude uses a skill, you see it in the “thinking” section if enabled . This shows: Which skills were activated What information was loaded How skills interacted This is invaluable for debugging and improving skills. If one skill relies on another, document it: Related Skills This skill works best when combined with: - data-validation skill for input checking - report-formatting skill for output styling Claude should load these skills when using this one for comprehensive workflows. When NOT to Use This Skill Don’t use this skill for: - Quick calculations use built-in math instead - Simple queries this skill is for complex analysis only - Real-time data use MCP connections for live data This helps Claude make better decisions about skill activation. Keep a log of times when: The skill didn’t activate when it should have The skill activated incorrectly The output wasn’t what you expected Use this to refine the description and instructions. The real magic happens when you combine Skills with MCP connections https://www.anthropic.com/news/model-context-protocol . Here’s a concrete example: Setup: MCP connection to your company’s PostgreSQL database MCP connection to your Slack workspace Skill: “Database Query Standards” Skill: “Slack Message Formatting” What you can do: “Check yesterday’s sales numbers and post a summary to the sales channel” Claude: Loads the Database Query Standards skill Writes a query following your conventions Executes it via MCP connection Loads the Slack Message Formatting skill Formats results according to team style Posts via MCP to Slack All of this happens automatically, consistently, following your standards. Skills will evolve. Here’s how to build them for longevity: version: 2.1.3 Major.Minor.Patch Major: Breaking changes to skill interface Minor: New features, backwards compatible Patch: Bug fixes and clarifications Assumptions This skill assumes: - Python 3.9+ is available - User has basic understanding of financial models - Data is in CSV format with headers - Date format is YYYY-MM-DD Deprecation Notice Status : Active will be deprecated 2026-03-01 Replacement : Use advanced-analysis-v2 skill instead Migration : Link to migration guide One skill, one purpose. Don’t try to make a skill that does everything. It’s easier to maintain five focused skills than one mega-skill. If you’re still reading, you’re probably convinced that Skills are worth exploring. Here’s my opinionated take on getting started: Start with: A code generation skill for your stack Include your team’s conventions Add linting rules Include common patterns Add a script to validate generated code Then build: A PR review skill Your review checklist Common issues in your codebase How to give constructive feedback Auto-generated review comments format Advanced: A deployment verification skill Pre-deployment checklist Post-deployment verification steps Rollback procedures Incident response templates Start with: Content formatting skill Your brand voice guidelines Content structure templates SEO best practices specific to your niche CTAs that work for your audience Then build: Research synthesis skill How you organize research notes Citation formats you prefer Insight extraction methods Content ideation from research Advanced: Multi-platform adaptation skill Blog post → Twitter thread converter Twitter thread → LinkedIn post adapter Long-form → Newsletter snippet generator Start with: Meeting notes skill Your meeting note template Action item formatting Who gets which type of follow-up Integration with your project management Then build: Report generation skill Company report templates KPI calculations Visualization preferences Distribution formatting Advanced: Process documentation skill SOP template Process mapping conventions Troubleshooting flowcharts Training material generation We’re at the very beginning of the Skills era. Right now November 2025 , Skills are: Two weeks old Understood by few Used by fewer Mastered by almost none This is your opportunity. In six months, there will be Skills for everything. There will be best practices, design patterns, and entire ecosystems. Companies will have libraries of organizational Skills. Freelancers will specialize in Skill creation. Courses will teach “Skills Engineering.” But right now? It’s wide open. The people who start building Skills today will be the experts everyone learns from tomorrow. The companies that encode their processes into Skills now will have a significant advantage over competitors who wait. This isn’t hype, it’s the logical evolution of how we work with AI. Skills turn one-off interactions into reusable expertise. They turn prompt engineering into knowledge engineering. They turn AI assistance into AI collaboration. Today: Enable Skills in your Claude account, try the pre-built document skills This week: Identify one repetitive task that has specific rules, use skill-creator to build your first custom skill This month: Create three skills that work together, share them with a colleague or community This quarter: Build a library of skills for your core workflows, measure the time saved And when you do, I’d love to hear about it. What skills are you building? What’s working? What surprised you? Because here’s the thing: Skills are so new that we’re all figuring this out together. Every experiment matters. Every insight contributes to the collective understanding. The revolution isn’t coming. It’s here. And it’s wearing the humble disguise of a Markdown file in a folder. Want to dive deeper? Check out Anthropic’s Skills GitHub repository https://github.com/anthropics/skills for examples, or join the discussion on r/ClaudeAI https://reddit.com/r/ClaudeAI . Final Note: This guide will become outdated. Skills are evolving rapidly. I’ll update it as I learn more, and I encourage you to treat Skills as an experiment, not a doctrine. Try things. Break things. Share what you learn. The best Skill you’ll ever create is the one you start building today. Originally published on nulltensor.com https://nulltensor.com/posts/getting-started-with-claude-skills/?utm source=devto&utm medium=crosspost&utm campaign=getting-started-with-claude-skills .