How to Create a New Skill

Relevant source files

The following files were used as context for generating this wiki page:

• .claude/skills/testing-patterns/SKILL.md
• README.md
• CLAUDE.md
• .claude/hooks/skill-rules.json
• .claude/settings.json
• .claude/hooks/skill-eval.sh

Introduction

Skills are markdown documents that teach Claude project-specific patterns, conventions, and domain knowledge. They are a core feature for customizing Claude to act as a "super-powered teammate" that understands your repository's specific standards. By creating skills, you ensure that code generated by Claude aligns with your project's architecture, style, and best practices out of the box.

This guide covers the structure of a skill, how to write one, and how to configure the system to automatically suggest skills based on user prompts. The goal is to build a reusable set of knowledge that makes development faster and more consistent.

Sources: README.md:5-8, 12-15, 415-416

Skill File Structure

All skills must be located within the .claude/skills/ directory. Each skill should have its own subdirectory, and the skill definition file must be named SKILL.md (case-sensitive).

Sources: README.md:83, 90, 417-418, 469

The required directory structure is visualized below.

For example, the skill for testing patterns is located at .claude/skills/testing-patterns/SKILL.md.

Sources: README.md:91-92

The SKILL.md Format

A SKILL.md file consists of two main parts: a YAML frontmatter for configuration and a markdown body for the instructional content.

Sources: README.md:121-124, 428

Frontmatter

The frontmatter contains metadata that Claude uses to understand and decide when to apply the skill. It is critical for both manual and automated skill activation.

Sources: README.md:131-132, 428-436

Field	Required	Max Length	Description
name	Yes	64 chars	A unique identifier in lowercase letters, numbers, and hyphens. It should match the skill's directory name.
description	Yes	1024 chars	A detailed explanation of what the skill does and when to use it. This is critical as Claude uses it for semantic matching to decide when to apply the skill.
allowed-tools	No	-	A comma-separated list of tools Claude is permitted to use with this skill (e.g., Read, Grep).
model	No	-	Specifies a particular model to use for this skill (e.g., claude-sonnet-4-20250514).

Sources: README.md:428-436

Here is an example from the testing-patterns skill:

---
name: testing-patterns
description: Jest testing patterns for this project. Use when writing tests, creating mocks, or following TDD workflow.
---

Sources: .claude/skills/testing-patterns/SKILL.md:1-4

Content Body

The body of the SKILL.md file is written in markdown and should provide clear instructions, patterns, and examples. A good structure includes:

• When to Use: Explicit conditions for when the skill should be applied.
• Core Patterns: "Do this" examples showing the correct implementation.
• Anti-Patterns: "Don't do this" examples of what to avoid.
• Integration: Notes on how this skill relates to other skills.

Sources: README.md:438-459

A generic template for a skill's body would look like this:

# Skill Title

## When to Use
- Trigger condition 1
- Trigger condition 2

## Core Patterns

### Pattern Name
```typescript
// Example of good code

Anti-Patterns

What NOT to Do

// Example of bad code

*Sources: [README.md:438-456](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/README.md#L438-L456)*

## Skill Activation

Skills can be activated either manually by the user or automatically suggested by the system based on the user's prompt.

### Manual Activation

The `CLAUDE.md` file can serve as a guide for developers, reminding them to use specific skills for certain tasks.

*Sources: [CLAUDE.md:45-46](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/CLAUDE.md#L45-L46)*

For example, it can contain a section that maps tasks to skills:
- Creating tests → `testing-patterns` skill
- Building forms → `formik-patterns` skill
- GraphQL operations → `graphql-schema` skill

*Sources: [CLAUDE.md:47-51](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/CLAUDE.md#L47-L51)*

### Automated Activation via Skill Evaluation Hooks

A more powerful method is the automated skill evaluation system, which runs on every prompt submission. This system analyzes the prompt and suggests relevant skills.

*Sources: [README.md:321-323](https://github.com/Alonso-pixel/claude-code-showcase/blob/HEAD/README.md#L321-L323)*

The process is triggered by a `UserPromptSubmit` hook defined in `.claude/settings.json`.

This diagram illustrates the automated skill evaluation flow:

1. Configure the Hook

To enable this system, you must add a UserPromptSubmit hook to your .claude/settings.json file that executes the evaluation script.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Sources: README.md:363-373, .claude/settings.json:28-40, .claude/hooks/skill-eval.sh

2. Define Activation Rules

The core of the evaluation engine is the .claude/hooks/skill-rules.json file. This file defines the triggers that map user intent to specific skills.

Sources: README.md:325, 347

The rules for each skill can include the following triggers:

Trigger	Description
keywords	An array of simple words that might appear in the prompt.
keywordPatterns	Regex patterns for more flexible keyword matching.
pathPatterns	Glob patterns to match against file paths mentioned in the prompt.
intentPatterns	Regex patterns to detect user intent (e.g., "fix a bug", "create a test").
excludePatterns	Patterns to prevent activation if matched.

Sources: README.md:328-332, 348-360, .claude/hooks/skill-rules.json:4-16

Below is an example configuration for the testing-patterns skill from skill-rules.json:

{
  "testing-patterns": {
    "description": "Jest testing patterns and TDD workflow",
    "priority": 9,
    "triggers": {
      "keywords": ["test", "jest", "spec", "tdd", "mock"],
      "keywordPatterns": ["\\btest(?:s|ing)?\\b", "\\bspec\\b"],
      "pathPatterns": ["**/*.test.ts", "**/*.test.tsx"],
      "intentPatterns": [
        "(?:write|add|create|fix).*(?:test|spec)",
        "(?:test|spec).*(?:for|of|the)"
      ]
    },
    "excludePatterns": ["e2e", "maestro", "end-to-end"]
  }
}

Sources: .claude/hooks/skill-rules.json:3-17, README.md:347-360

Best Practices for Writing Skills

To create effective skills, follow these guidelines:

1. Keep Skills Focused: Each SKILL.md should cover a single, well-defined domain. Keep the file under 500 lines for clarity.
2. Write Trigger-Rich Descriptions: The description frontmatter is crucial. Use keywords and phrases that a developer would naturally use when discussing the topic, as Claude relies on this for semantic matching.
3. Include Concrete Examples: Provide both good and bad code snippets to clearly illustrate patterns and anti-patterns.
4. Reference Other Skills: If skills are related, mention how they work together to build a connected knowledge base.
5. Use the Correct Filename: The file must be named SKILL.md.

Sources: README.md:461-469

Conclusion

Creating skills is a fundamental practice for leveraging Claude Code effectively. By documenting project-specific knowledge in a structured format, you empower Claude to act as an extension of your team, enforcing conventions, accelerating development, and improving code quality. The combination of well-written SKILL.md files and an automated skill evaluation system creates a powerful feedback loop that keeps Claude's output consistently aligned with your project's evolving standards.

Sources: README.md:5-8, 12-15