Documentation > Tutorials > Creating Your First Skill

Guide ID	T-1
Audience	All users
Prerequisites	GS-1: Installation & Setup complete
Time	15 minutes
Difficulty	Beginner

Creating Your First Skill

This tutorial walks you through creating, validating, and testing your first skill from scratch. By the end, you will have a working skill with passing tests that you can use as a template for future skills. The entire process takes about 15 minutes and requires five commands.

Step 1: Create the Skill

Run the interactive skill creation wizard. This guides you through naming the skill, writing a description, and adding content:

skill-creator create

Follow the prompts carefully:

• Name: Enter my-first-skill. Skill names must be lowercase with hyphens only — no spaces, underscores, or uppercase letters.
• Description: Enter Use when learning about skill-creator. Activate when user mentions tutorial, getting started, or first skill. The “Use when…” pattern is critical for reliable activation. It tells Claude exactly when this skill is relevant.
• Content: Enter instructions or knowledge for the skill. This is the Markdown body that Claude will load into context when the skill activates.

Step 2: Validate the Skill

Check that your skill follows the official Claude Code format. Validation catches structural problems before they cause activation issues:

skill-creator validate my-first-skill

The validator runs four checks:

• Name format valid — The name uses only lowercase letters, digits, and hyphens
• Directory structure valid — The skill lives in a properly named subdirectory with a SKILL.md file
• Metadata schema valid — The YAML frontmatter contains the required fields with correct types
• Directory/name match — The directory name matches the name field in frontmatter

Step 3: Generate Test Cases

Automated test cases verify that your skill activates for the right prompts and stays silent for unrelated ones. Generate tests from your skill description:

skill-creator test generate my-first-skill

The generator creates two types of test cases:

• Positive tests — Prompts where the skill should activate (e.g., “tell me about getting started”)
• Negative tests — Prompts where the skill should not activate (e.g., “delete all files”)

You will review each generated test case and can approve, edit, or skip individual tests before they are saved.

Step 4: Run Tests

Execute the test suite to measure how accurately your skill activates:

skill-creator test run my-first-skill

The test runner simulates activation for each prompt and compares the result against the expected behavior. You will see a pass/fail result for each test case along with the confidence score.

Step 5: Simulate Activation

Test your skill against specific prompts to see exactly what would happen during a real session:

skill-creator simulate "help me get started with skill-creator"

The simulate command predicts which skill would activate for the given prompt. Use verbose mode for detailed scoring information:

skill-creator simulate "help me get started with skill-creator" --verbose

Try a few different prompts to build confidence in your skill’s activation behavior. Test both prompts that should activate the skill and prompts that should not.

Summary

You have completed the full skill lifecycle: create, validate, generate tests, run tests, and simulate. These five steps form the foundation of every skill you build. As your skills accumulate, you can use additional tools like conflict detection and threshold calibration to maintain quality across your skill library.

What’s Next

• Skill Format Guide — Learn about frontmatter fields, effective descriptions, and the official vs extension format
• Detecting Conflicts — Find and resolve semantic overlap between skills to prevent activation confusion