# How to Create and Use Custom Skills for Domain‑Specific Tasks in Claude Code > Learn to create and use custom skills for domain-specific tasks in Claude Code. Scaffold, populate, and invoke your own knowledge modules to enhance Claude's capabilities. - Repository: [Affaan Mustafa/everything-claude-code](https://github.com/affaan-m/everything-claude-code) - Tags: how-to-guide - Published: 2026-03-20 --- **Claude Code skills are self‑contained knowledge modules stored in `skills//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`](https://github.com/affaan-m/everything-claude-code/blob/main/SKILL.md)) resides at `skills//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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/SKILL.md) following the **Agent‑First, Plan‑Before‑Execute** workflow. ```bash /skill-create --commits 150 --output ./skills/semantic-search ``` This creates [`skills/semantic-search/SKILL.md`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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. ```bash /skill-create --commits 150 --output ./skills/semantic-search --instincts ``` ```bash /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//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. ```markdown --- 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: ```text 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//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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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`](https://github.com/affaan-m/everything-claude-code/blob/main/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//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`](https://github.com/affaan-m/everything-claude-code/blob/main/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.