Automated skill builder for Claude Code - Describe a skill you need, and Claude Code generates it following best practices automatically.

Skilz is a guidelines repository that teaches Claude Code how to write high-quality skills. It contains:

1. skill-builder skill - A meta-skill that Claude loads to learn how to write skills
2. Comprehensive evaluations - 12 test cases to validate skill quality
3. Comprehensive templates - 8 ready-to-use skill patterns
4. Complete examples - Production-quality skill examples demonstrating best practices
5. Validation tools - Automated checking of skill requirements
6. Full documentation - Everything you need to understand skills

Note: This repository contains only the guidelines and tools for building skills. It does not contain specific skill implementations. The skills you create using this repository should be tracked in their own repositories or in your project's .claude/skills/ directory.

# Clone the guidelines repository
git clone <your-repo-url> skilz
cd skilz
npm install

Important: This repo contains guidelines only. Your skills go elsewhere:

• Project skills: your-project/.claude/skills/
• Personal skills: ~/.claude/skills/
• Team skills: team-skills/.claude/skills/

See SETUP.md for complete setup guide.

Navigate to your project (NOT the skilz repo):

cd ~/projects/my-app  # Your actual project

Ask Claude to create a skill:

You: Create a skill for analyzing SQL query performance

Claude: I'll create a skill for SQL query performance analysis...
[Creates: my-app/.claude/skills/sql-analyzer/SKILL.md] ✅

Claude Code automatically:

• Loads skill-builder guidelines from skilz repo
• Structures YAML frontmatter correctly
• Writes effective descriptions with triggers
• Applies appropriate patterns (analysis, workflow, etc.)
• Uses progressive disclosure when needed
• Follows all best practices

Result: Skill is created in YOUR project, not in skilz ✅

# From your project directory
node ~/projects/skilz/tools/validate-skill.js .claude/skills/sql-analyzer

# Or use npm script from skilz repo
cd ~/projects/skilz
npm run validate ~/projects/my-app/.claude/skills/sql-analyzer

Output:

✓ name field valid: sql-analyzer
✓ description field valid (245 chars)
✓ SKILL.md length: 287 lines
✓ No Windows-style paths found
✓ All validations passed!

Your skill is now ready! When you're in your project directory, Claude Code automatically uses it when relevant.

• SETUP.md - Complete setup and organization guide
• DIRECTORY-STRUCTURE.md - Where to put skills
• CONTRIBUTING.md - How to contribute to guidelines

The core of this repository is .claude/skills/skill-builder/SKILL.md - a skill that teaches Claude how to write skills.

When you ask Claude Code to create a skill, it:

1. Loads skill-builder - The meta-skill activates automatically
2. Applies best practices - Follows conciseness, progressive disclosure, workflows
3. Chooses right pattern - Selects appropriate template (analysis, workflow, etc.)
4. Generates valid structure - Creates proper YAML frontmatter and organization
5. Validates requirements - Ensures name/description format is correct

You ask:

Create a skill for reviewing API designs

Claude Code:

1. Recognizes this is a skill creation request
2. Loads .claude/skills/skill-builder/SKILL.md
3. Determines this needs the "analysis-skill" pattern
4. Generates complete SKILL.md with:
   • Valid YAML frontmatter (name: reviewing-api-designs)
   • Specific description with triggers
   • Structured analysis process
   • Checklist workflow
   • Output template
   • Examples

Result: A production-ready skill following all best practices.

skilz/                               # GUIDELINES REPOSITORY
├── README.md                        # You are here
├── package.json                     # Node.js tooling
│
├── .claude/
│   └── skills/
│       └── skill-builder/           # THE META-SKILL (guidelines)
│           ├── SKILL.md             # Main skill teaching Claude
│           ├── EVALUATIONS.md       # Testing guide
│           ├── evaluations.json     # 12 test cases
│           ├── best-practices.md    # Core principles
│           ├── structure-reference.md
│           ├── patterns.md          # Pattern library
│           ├── validation-rules.md
│           └── examples/            # Inline examples
│
├── docs/                            # Comprehensive documentation
│   ├── README.md
│   ├── best-practices-guide.md
│   ├── skill-structure.md
│   └── ...
│
├── templates/                       # 8 ready-to-use templates
│   ├── basic-skill/
│   ├── analysis-skill/
│   ├── generation-skill/
│   ├── workflow-skill/
│   ├── tool-restricted-skill/
│   ├── multi-file-skill/
│   ├── script-based-skill/
│   └── validation-skill/
│
├── examples/                        # Production-quality examples
│   └── code-reviewer/
│       ├── SKILL.md
│       └── README.md (design notes)
│
└── tools/                           # Validation and scaffolding
    ├── validate-skill.js
    ├── scaffold-skill.js
    ├── lint-skill.js
    └── test-skill.js

Note: This structure contains only guidelines and templates. Your actual skills should be created in:

• Project skills: your-project/.claude/skills/your-skill/
• Personal skills: ~/.claude/skills/your-skill/
• Separate repositories: For skills you want to share independently

The skill-builder teaches Claude these core principles:

Only include what Claude doesn't already know:

• ✗ Don't explain what PDFs are
• ✗ Don't explain how npm works
• ✓ Do provide specific commands
• ✓ Do document domain conventions

Match specificity to task fragility:

• High freedom: Text instructions for flexible tasks
• Medium freedom: Pseudocode for preferred patterns
• Low freedom: Exact scripts for critical operations

Structure content for on-demand loading:

• SKILL.md as table of contents
• Details in separate files
• Claude reads only what's needed

For multi-step tasks:

• Provide checkbox checklists
• Clear validation points
• Validate → Fix → Repeat pattern

Comprehensive test suite ensures quality:

• 12 evaluation test cases covering all skill aspects
• Baseline comparison to measure improvement
• Success criteria (10/12 passing = 83%)
• Iteration guidance for continuous improvement

See .claude/skills/skill-builder/EVALUATIONS.md for complete testing guide.

You: Create a skill for formatting JSON files

Claude: [Generates basic-skill pattern with proper structure]

You: Create a skill for reviewing database schemas

Claude: [Generates analysis-skill pattern with:
- Structured review process
- Checkbox workflow
- Output template
- Finding categorization]

You: Create a skill for deploying applications safely

Claude: [Generates workflow-skill pattern with:
- Multi-step process
- Validation at each step
- Error recovery
- Feedback loops]

npm run validate .claude/skills/json-formatter
# ✓ All validations passed!

To use a skill with Claude web (claude.ai), create a properly structured zip file:

You: Package this skill for Claude web

Claude: [Creates zip with SKILL.md at top level, not nested]

Key requirement: SKILL.md must be at the top level of the zip file.

See docs/packaging-for-claude-web.md for complete packaging guide.

You can also copy templates manually:

# Copy template to your project
cp -r templates/analysis-skill .claude/skills/my-analyzer

# Edit SKILL.md
vim .claude/skills/my-analyzer/SKILL.md

# Validate
npm run validate .claude/skills/my-analyzer

Check technical requirements:

npm run validate path/to/skill

Validates:

• YAML frontmatter syntax
• Name format (lowercase, hyphens, max 64 chars)
• Description length (max 1024 chars)
• File paths (forward slashes)
• Referenced files exist
• No Windows-style paths

Interactive skill generator:

npm run scaffold

Prompts for:

• Skill name
• Description
• Template choice
• Location (project vs personal)

Check best practices:

npm run lint path/to/skill

Checks:

• Markdown formatting
• Consistency
• Verbosity
• Anti-patterns

Test skill behavior:

npm run test path/to/skill

Tests:

• Trigger recognition
• File navigation
• Workflow completeness

---
name: lowercase-with-hyphens
description: What it does and when to use it. Use when [triggers].
---

name:

• Lowercase, hyphens, max 64 chars
• No reserved words (anthropic, claude)
• Prefer gerund form: processing-pdfs, analyzing-data

description:

• Max 1024 chars, third person
• Include WHAT and WHEN
• Include trigger keywords

• SKILL.md under 500 lines
• Forward slashes in all paths
• References one level deep from SKILL.md
• Consistent terminology
• Concrete examples
• No time-sensitive information

Template Pattern: Structure output format Examples Pattern: Show input/output pairs Workflow Pattern: Multi-step with checkboxes Validation Pattern: Plan-validate-execute

Complete guides in docs/:

• best-practices-guide.md - Complete authoring guide
• skill-structure.md - Technical specifications
• progressive-disclosure.md - Content organization
• workflows-and-feedback.md - Multi-step processes
• testing-and-evaluation.md - Testing skills
• security-considerations.md - Security guidelines

Browse examples/ for production-quality skills:

Complete read-only analysis skill demonstrating:

• Tool restrictions (allowed-tools: Read, Grep, Glob)
• Structured workflow with checklist
• Severity classification
• Concrete examples
• Appropriate conciseness

See examples/code-reviewer/README.md for detailed design notes.

You: Create a skill for building and optimizing PostgreSQL queries

Claude Code: [Generates skill with:
- Query construction patterns
- Optimization guidelines
- Index usage recommendations
- Performance analysis steps
- Common patterns reference]

You: npm run validate .claude/skills/postgres-queries

Output: ✓ All validations passed!

You: Create a skill for generating comprehensive test suites

Claude Code: [Generates generation-skill with:
- Test structure templates
- Coverage guidelines
- Mock/stub patterns
- Edge case considerations
- Examples for unit/integration tests]

You: Create a skill for safely deploying to production

Claude Code: [Generates workflow-skill with:
- Pre-deployment checklist
- Validation at each step
- Rollback procedures
- Health checks
- Post-deployment verification]

• No manual skill writing: Describe what you need, get a complete skill
• Best practices automatic: Claude applies all guidelines
• Consistent quality: Every skill follows same standards
• Quick iteration: Generate, validate, test, refine

• Shared knowledge: Package expertise as skills
• Onboarding: New team members get access to team skills
• Consistency: Everyone uses same approaches
• Version control: Skills tracked in git

It's a skill that Claude Code loads when you ask to create a skill. It contains all best practices, patterns, and requirements. Claude reads it and applies the knowledge to generate your skill.

No! Just describe what you need. Claude handles the structure, formatting, and best practices automatically.

Yes! Generated skills are starting points. Edit them to fit your specific needs.

Put skills in .claude/skills/ in your project repository. Anyone who clones the repo gets the skills. Do not commit specific skills to this skilz repository - it's only for guidelines.

The validator provides specific error messages. Fix the issues it identifies and validate again.

Yes! Describe language-specific patterns and Claude will incorporate them.

Pull the latest version of this repository to get updates to the meta-skill, templates, and tools.

Found a useful pattern? Have a great example?

1. Document your pattern
2. Create a reusable template
3. Add comprehensive examples
4. Submit a pull request

• Anthropic Docs: Skills Overview
• Best Practices: Skill Authoring Guide
• Claude Cookbooks: Skills Examples

1. Try it: Ask Claude Code to "create a skill for [your use case]"
2. Validate: Run npm run validate on the generated skill
3. Use it: The skill activates automatically when relevant
4. Iterate: Refine based on usage
5. Share: Commit skills to your project for team access

MIT

• Documentation: See docs/ directory
• Examples: See examples/ directory
• Issues: Open a GitHub issue
• Questions: Check documentation first

Happy skill building! 🚀

The skill-builder skill is ready to generate high-quality, best-practice-compliant skills for all your needs.