Feature: Skills (Domain Knowledge)

Relevant source files

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

• README.md
• CLAUDE.md
• .claude/skills/testing-patterns/SKILL.md
• .claude/skills/graphql-schema/SKILL.md
• .claude/skills/systematic-debugging/SKILL.md
• .claude/skills/react-ui-patterns/SKILL.md
• .claude/hooks/skill-rules.json

Skills are markdown documents that provide Claude with project-specific domain knowledge, patterns, and conventions. They are a core feature for ensuring that AI-generated code aligns with the repository's established standards and best practices. By defining skills for common tasks like testing, UI development, or API interaction, developers can guide Claude to operate like a "super-powered teammate" that already understands the project's specific ways of working.

The primary goal of the Skills system is to automate adherence to coding patterns, reducing manual review effort and increasing consistency across the codebase. This is achieved by creating a library of reusable knowledge that can be automatically or manually activated. This system is complemented by Skill Evaluation Hooks, which intelligently suggest relevant skills based on user prompts.

Sources: README.md:5-8, README.md:642-643

Skill Architecture

Skills are organized in a dedicated directory and follow a specific file structure and format to be correctly interpreted by Claude.

Sources: README.md:642-644

Directory Structure

All skills are located within the .claude/skills/ directory. Each skill must be placed in its own subdirectory, and the knowledge document itself must be named SKILL.md (case-sensitive).

Sources: README.md:78-86, README.md:667

This diagram illustrates the required directory layout for a skill.

SKILL.md File Format

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

Sources: README.md:651-668

Frontmatter Configuration

The frontmatter contains metadata that Claude uses to understand the skill's purpose and context. The description field is particularly critical, as it is used for semantic matching to determine when the skill should be applied.

Sources: README.md:200-201, README.md:664

Field	Required	Max Length	Description
name	Yes	64 chars	Lowercase, hyphenated name that must match the parent directory name.
description	Yes	1024 chars	A detailed explanation of the skill's purpose and when it should be used. Rich with keywords for activation.
allowed-tools	No	-	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:652-659

Here is an example of a SKILL.md frontmatter:

---
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:2-4

Content Body

The body of the SKILL.md file is written in markdown and should clearly explain the patterns and conventions. Recommended sections include:

• When to Use: Explicit trigger conditions for the skill.
• Core Patterns: "Do this" examples with good code snippets.
• Anti-Patterns: "Don't do this" examples with bad code snippets.
• Integration: How this skill relates to other skills or parts of the codebase.

Sources: README.md:661-674

Skill Activation

Skills can be activated manually by the user or automatically through a sophisticated hook-based evaluation system. The CLAUDE.md file also serves as a high-level guide, instructing Claude to check for relevant skills before starting a task.

Sources: CLAUDE.md:46-54, README.md:550-552

Automatic Activation via Skill Evaluation Hooks

The repository includes a powerful automation for suggesting skills called the skill evaluation system. This system is triggered by the UserPromptSubmit hook and analyzes the user's prompt to recommend relevant skills.

Sources: README.md:550-552, README.md:620-629

The activation process follows these steps:

1. A user submits a prompt.
2. The UserPromptSubmit hook executes the skill-eval.sh script.
3. The script runs a Node.js engine (skill-eval.js) that analyzes the prompt against rules defined in skill-rules.json.
4. The engine analyzes the prompt for keywords, regex patterns, file paths, and user intent.
5. Each match contributes to a confidence score for associated skills.
6. Skills that exceed a confidence threshold are suggested to the user for activation.

Sources: README.md:554-572

This flowchart shows the automated skill suggestion workflow.

Trigger Configuration

The logic for matching prompts to skills is defined in .claude/hooks/skill-rules.json. Each skill can have a set of triggers, including keywords, regex patterns, and file path patterns.

Sources: README.md:586-604

{
  "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, README.md:586-604

Example Skills

The repository contains several pre-defined skills that serve as a template for creating new ones.

Skill Name	Purpose
testing-patterns	Defines conventions for TDD, factory functions for mocking, and Jest test structure.
systematic-debugging	Outlines a four-phase methodology for debugging issues.
react-ui-patterns	Covers handling of loading, error, and empty states in UI components.
graphql-schema	Details how to write GraphQL queries and mutations, and how to use codegen.
core-components	Documents the project's design system and component library.
formik-patterns	Provides patterns for form handling and validation using Formik.

Sources: README.md:646-651, README.md:778-784

Best Practices for Creating Skills

To ensure skills are effective, follow these guidelines:

1. Keep Skills Focused: Each SKILL.md should cover a single domain and be under 500 lines.
2. Write Rich Descriptions: The description frontmatter is crucial for automatic activation. Use keywords a developer would naturally use when discussing the topic.
3. Use Concrete Examples: Provide both good and bad code examples to clearly illustrate patterns and anti-patterns.
4. Reference Other Skills: Create a connected web of knowledge by showing how different skills relate to one another.
5. Use the Correct Filename: The skill document must be named SKILL.md.

Sources: README.md:663-675

Conclusion

The Skills feature is a foundational element of the Claude Code integration, enabling teams to codify their domain-specific knowledge and development conventions. By creating a comprehensive library of skills, projects can leverage Claude not just for generic code generation, but as an expert assistant that understands and adheres to the project's unique architecture and standards. This system significantly improves the quality and consistency of AI-assisted development while automating adherence to best practices.

Sources: README.md:5-8