Domain Skills Overview

Overview of Domain Skills

Domain Skills are the specialized knowledge base of your Claude Code implementation. Instead of re-explaining your project’s architecture, UI patterns, or testing standards in every prompt, you codify this information into reusable modules. This allows Claude to operate as a "super-powered teammate" who already knows exactly how your specific codebase should be written and maintained.

By storing skills in the .claude/skills/ directory, you ensure that AI-generated code matches your internal standards out of the box.

How Skills Work

Skills are primarily defined as Markdown files that Claude reads when relevant to a task. They act as a persistent memory layer for your technical requirements.

Skill Directory Structure

A typical skill is organized within a dedicated sub-directory:

.claude/
└── skills/
    ├── core-components/
    │   └── SKILL.md          # Documentation on UI library usage
    ├── testing-patterns/
    │   └── SKILL.md          # Standards for Jest/Cypress tests
    └── graphql-schema/
        └── SKILL.md          # Patterns for mutations and queries

Intelligent Skill Activation

You don't need to manually tell Claude which skill to use. The project includes a Skill Evaluation Engine (.claude/hooks/skill-eval.js) that automatically activates relevant domain knowledge based on the context of your request.

The engine analyzes several factors to determine which skill to "inject" into Claude's context:

• Keyword Detection: If your prompt contains words like "button," "layout," or "theme," the engine can trigger the core-components skill.
• File Path Awareness: Mentioning or editing files in src/components/ automatically flags UI-related skills.
• Intent Pattern Matching: If the engine detects you are writing a test (based on regex patterns or file extensions like .test.ts), it activates the testing-patterns skill.
• Priority Scoring: Skills are ranked so that the most relevant domain knowledge is prioritized when multiple rules match.

Configuration: skill-rules.json

The behavior of the evaluation engine is governed by a rules file. This is where you map keywords and paths to specific skills:

{
  "skills": {
    "core-components": {
      "triggers": {
        "keywords": ["atomic", "components", "design system"],
        "paths": ["src/components/**", "src/ui/**"]
      },
      "priority": 10
    },
    "testing-patterns": {
      "triggers": {
        "keywordPatterns": ["write a test", "fix the test"],
        "globPatterns": ["**/*.test.ts", "**/*.spec.js"]
      }
    }
  }
}

Writing Effective Skills

To get the best results from Claude, your SKILL.md files should be structured for clarity and actionability. Focus on the following sections:

1. Context: What is this skill for?
2. Usage Examples: Provide "Golden Code" snippets that show the correct way to implement a pattern.
3. Anti-Patterns: Explicitly list what Claude should not do (e.g., "Don't use inline styles; always use the styled-system props").
4. Checklist: A short list of requirements Claude must verify before finishing a task.

Example: UI Library Skill

# Skill: Core UI Components

## Purpose
Guidelines for using our internal Radix-based component library.

## Standards
- Always use the `Box` component for layout/spacing.
- Use `Text` variants (h1, p, label) instead of raw HTML tags.
- All interactive elements must include `aria-label` for accessibility.

## Example
<Box gap="md" padding="lg">
  <Text variant="h1">Hello World</Text>
</Box>

Benefits of Codified Skills

• Consistency: Every developer on the team (and the AI) follows the exact same patterns.
• Reduced Friction: You spend less time correcting minor stylistic or architectural errors in AI outputs.
• Automated Onboarding: New developers can use Claude Code to learn the repo's conventions simply by asking questions, as Claude will reference the domain skills to answer.
• Quality Gates: Skills can be paired with Custom Agents to perform deep code reviews against your specific standards before a PR is even opened.