How to Create and Use Custom Skills for Domain‑Specific Tasks in Claude Code

Claude Code skills are self‑contained knowledge modules stored in skills/<name>/SKILL.md that you scaffold with /skill-create, populate with domain‑specific guidance, and invoke either explicitly via slash commands or automatically through trigger‑term detection.

Claude Code supports extensible domain expertise through a skill system defined in the affaan-m/everything-claude-code repository. These modular knowledge units live as Markdown files with structured front matter, allowing the assistant to load specialized context only when needed. The architecture follows an Agent‑First, Plan‑Before‑Execute principle, ensuring skills are drafted and validated before any implementation begins.

Understanding the Skill Architecture

A Claude Code skill consists of three core components that work together to provide lazy‑loaded expertise without bloating the baseline context.

The Skill File (SKILL.md) resides at skills/<name>/SKILL.md and contains the complete domain guide, including activation triggers, core principles, and implementation patterns. According to the reference implementation in skills/api-design/SKILL.md, every skill must include YAML front matter with name, description, and origin fields followed by structured Markdown sections.

The Skill Loader documented in docs/AGENTS.md maintains a runtime trigger table that maps keywords to skill paths. This system ensures skills are fetched from disk and injected into the model’s context only when relevant terminology appears in the conversation.

The Scaffold Command /skill-create (documented in docs/zh-CN/commands/skill-create.md) automates skill creation by examining recent Git history to detect repository patterns, commit conventions, and folder layouts.

Creating a Custom Skill Step by Step

Step 1: Scaffold the SKILL.md File

Run the internal scaffold command to analyze your repository’s recent Git history and detect patterns such as commit conventions, folder layout, and test placement. The command generates a ready‑to‑edit SKILL.md following the Agent‑First, Plan‑Before‑Execute workflow.

/skill-create --commits 150 --output ./skills/semantic-search

This creates skills/semantic-search/SKILL.md with the required front‑matter structure and placeholder sections for domain guidance.

Step 2: Edit the Generated File

Open the new SKILL.md and complete the domain‑specific sections. Ensure the YAML front matter includes the name, description, and origin fields. Populate the following sections to define when and how the skill applies:

• When to Activate: List conditions that trigger auto‑loading (e.g., "Building a hybrid search feature")
• Core Principles: Architectural rules specific to the domain
• Implementation Patterns: Concrete code examples and file paths

Refer to skills/customs-trade-compliance/SKILL.md for an example of domain‑specific compliance rules and structured metadata.

Step 3: Generate Instincts and Commit

Optionally add the --instincts flag to create a .claude/evals/ file containing automated evaluation criteria. Import these with /instinct-import and commit the skill using conventional commits (feat: add semantic-search skill). Run the repository’s verification loop, potentially validating the skill with the tdd-guide agent before finalizing.

/skill-create --commits 150 --output ./skills/semantic-search --instincts

/instinct-import ./skills/semantic-search/instincts.yml

Activating and Using Skills

You can invoke a skill through two mechanisms designed for flexibility and performance.

Explicit Invocation: Type /my-skill (where my-skill matches the name field in the front matter) to force immediate loading of the knowledge module from skills/<name>/SKILL.md.

Automatic Detection: Claude Code monitors prompts for trigger terms defined in the skill’s When to Activate section. When you mention "semantic search" or "custom validation," the runtime lazily loads the corresponding skill and injects its guidance into the context window.

Because the system uses lazy loading, skills add virtually no overhead to standard sessions; only the relevant file is read from disk when triggers match.

Practical Example: Semantic Search Skill

Below is a complete example of a custom skill for vector search implementation, following the structure validated in the affaan-m/everything-claude-code repository.

---
name: semantic-search
description: Guide for building domain‑specific vector search pipelines.
origin: ECC
---

# Semantic Search

## When to Activate

- Building a hybrid search feature
- Adding a new embedding model
- Optimising relevance ranking

## Core Principles

- Keep the embedding generation pure and deterministic
- Cache results in Redis (see caching pattern)
- Fall back to substring search if the vector service is unavailable

During a session, the interaction works as follows:

User: I need to add a semantic search endpoint for products.
Claude: (loads semantic-search skill) Here’s a step‑by‑step plan …

Summary

• Skills are modular knowledge units stored in skills/<name>/SKILL.md with strict front‑matter requirements including name, description, and origin.
• The /skill-create command scaffolds new skills by analyzing Git history and repository patterns, with optional --instincts generation for automated evaluation.
• Lazy loading via the trigger table in docs/AGENTS.md ensures skills activate only when relevant, minimizing context bloat.
• Skills can be invoked explicitly with /skill-name or automatically via keyword detection defined in the When to Activate section.
• The system follows conventional commits and verification loops to ensure skill quality before deployment.

Frequently Asked Questions

What file format does a Claude Code skill use?

Skills use Markdown files with YAML front matter named SKILL.md. The front matter must include name, description, and origin fields, followed by structured sections like When to Activate and Core Principles as shown in skills/api-design/SKILL.md.

How does Claude Code know when to load a skill automatically?

The runtime maintains a trigger table documented in docs/AGENTS.md that maps keywords to skill file paths. When your prompt contains terms listed in a skill’s When to Activate section, the loader fetches that specific SKILL.md from disk and injects its contents into the model context.

Can I create skills without using the /skill-create command?

Yes. While /skill-create automates pattern detection from Git history, you can manually create skills/<name>/SKILL.md following the front‑matter schema and section structure defined in the repository’s reference implementations. Validate your file against existing examples like skills/customs-trade-compliance/SKILL.md.

What is the performance impact of adding many skills?

Skills add negligible overhead because they are lazy‑loaded. The system only reads a skill file from disk when its trigger keywords are detected or when explicitly invoked via the / command, ensuring the baseline context remains lightweight regardless of how many skills exist in the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}