Feature: Intelligent Skill Evaluation

Relevant source files

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

• .claude/hooks/skill-eval.sh
• .claude/hooks/skill-eval.js
• .claude/hooks/skill-rules.json
• README.md
• .claude/settings.json
• CLAUDE.md

# Feature: Intelligent Skill Evaluation

The Intelligent Skill Evaluation system is an automated feature designed to enhance Claude's contextual awareness by dynamically suggesting relevant skills based on user input. It hooks into the prompt submission process to analyze the user's query, match it against a predefined set of rules, and recommend which skills should be activated for the current task. This ensures that project-specific patterns and conventions, such as those for testing, GraphQL, or UI components, are consistently applied.

This system is composed of a shell script hook, a Node.js evaluation engine, and a JSON configuration file for rules. It provides immediate feedback to the user, ranking suggested skills by relevance and explaining the reasons for their activation, thereby streamlining the development workflow and improving the quality of generated code.

Sources: README.md:290-293, CLAUDE.md:46-54

System Architecture and Data Flow

The skill evaluation process is initiated every time a user submits a prompt. It follows a clear sequence, starting from the hook trigger defined in settings.json to the final suggestion output.

Sources: README.md:295-296

The following diagram illustrates the high-level data flow of the skill evaluation system.

Sequence of Operations

The interaction between the components is orchestrated by the UserPromptSubmit hook.

Configuration

The system's behavior is primarily defined by two configuration files: settings.json for hook registration and skill-rules.json for the matching logic.

Hook Registration

The evaluation process is enabled by registering the skill-eval.sh script to the UserPromptSubmit hook in .claude/settings.json.

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

This configuration ensures that for every prompt submitted by the user, the shell script is executed.

Sources: README.md:330-343

Skill Rules Definition

The core of the matching logic resides in .claude/hooks/skill-rules.json. This file defines each skill, its triggers, and its priority.

An example configuration for a testing-patterns skill is shown below:

{
  "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:320-329

The structure of a skill rule is defined by several key properties:

Property	Description
description	A brief explanation of the skill's purpose.
priority	A numeric value indicating the skill's importance (higher is more important).
triggers	An object containing patterns that can activate the skill.
excludePatterns	A list of keywords that, if present, will prevent the skill from being suggested.

Sources: README.md:320-329

Core Logic and Prompt Analysis

The skill-eval.js script is the engine that performs the analysis. It processes the user's prompt against the rules defined in skill-rules.json.

Sources: .claude/hooks/skill-eval.js, README.md:295-305

Analysis Triggers

The engine analyzes the prompt for several types of triggers:

Trigger Type	Description
Keywords	Simple word matching (e.g., test, graphql).
Patterns	Regular expression matching (e.g., `\btest(?:s
File Paths	Extracts and analyzes file paths mentioned in the prompt.
Intent	Detects user intent through patterns (e.g., create.*test).

Sources: README.md:298-302

Directory Mapping

The system can also map file paths found in the prompt to specific skills. This is useful for associating directories with certain domains.

{
  "src/components/core": "core-components",
  "src/graphql": "graphql-schema",
  ".github/workflows": "github-actions",
  "src/hooks": "react-ui-patterns"
}

Sources: README.md:304-310

Confidence Scoring

To rank the relevance of matched skills, the engine uses a point-based confidence scoring system. Each trigger type contributes a specific point value.

Trigger Type	Point Value
keyword	2
keywordPattern	3
pathPattern	4
directoryMatch	5
intentPattern	4

Skills that exceed a certain confidence threshold are then suggested to the user.

Sources: README.md:312-320

Summary

The Intelligent Skill Evaluation feature is a powerful automation that bridges the gap between user intent and project-specific knowledge. By analyzing prompts and automatically suggesting relevant skills, it ensures that developers adhere to established conventions with minimal effort. This system significantly improves consistency and efficiency, making Claude a more integrated and effective "super-powered teammate".

Sources: README.md:10, README.md:290-293