my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

---
name: my-skill
description: What this skill does and when to use it
argument-hint: "[filename] [format]"        # Hint for autocomplete
disable-model-invocation: true              # Only user can invoke
user-invocable: false                       # Hide from slash menu
allowed-tools: Read, Grep, Glob             # Restrict tool access
disallowed-tools: Write, Edit               # Remove specific tools while active (v2.1.152)
model: opus                                 # Specific model to use
effort: high                                # Effort level override (low, medium, high, xhigh, max)
context: fork                               # Run in isolated subagent
agent: Explore                              # Which agent type (with context: fork)
background: false                           # Fork skills run in background (default true); false = foreground
shell: bash                                 # Shell for commands: bash (default) or powershell
hooks:                                      # Skill-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
paths: "src/api/**/*.ts"               # Glob patterns limiting when skill activates
---

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

---
name: fix-issue
description: Fix a GitHub issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

## Практические примеры

### Пример 1: skill для code review

**Структура каталога:**

**Файл:** `~/.claude/skills/code-review-specialist/SKILL.md`
```yaml
---
name: code-review-specialist
description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization.
---

# Code Review Skill

This skill provides comprehensive code review capabilities focusing on:

1. **Security Analysis**
   - Authentication/authorization issues
   - Data exposure risks
   - Injection vulnerabilities
   - Cryptographic weaknesses

2. **Performance Review**
   - Algorithm efficiency (Big O analysis)
   - Memory optimization
   - Database query optimization
   - Caching opportunities

3. **Code Quality**
   - SOLID principles
   - Design patterns
   - Naming conventions
   - Test coverage

4. **Maintainability**
   - Code readability
   - Function size (should be < 50 lines)
   - Cyclomatic complexity
   - Type safety

## Review Template

For each piece of code reviewed, provide:

### Summary
- Overall quality assessment (1-5)
- Key findings count
- Recommended priority areas

### Critical Issues (if any)
- **Issue**: Clear description
- **Location**: File and line number
- **Impact**: Why this matters
- **Severity**: Critical/High/Medium
- **Fix**: Code example

For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md).

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

Входящий в комплект Python-скрипт берёт на себя основную работу, а Claude отвечает за оркестрацию.

### Пример 3: Skill для развёртывания (только по явному вызову пользователем)
```yaml
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Push to the deployment target
4. Verify the deployment succeeded
5. Report deployment status
```
### Пример 4: Skill «Голос бренда» (справочные знания)
```yaml
---
name: brand-voice
description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content.
user-invocable: false
---

## Tone of Voice
- **Friendly but professional** - approachable without being casual
- **Clear and concise** - avoid jargon
- **Confident** - we know what we're doing
- **Empathetic** - understand user needs

## Writing Guidelines
- Use "you" when addressing readers
- Use active voice
- Keep sentences under 20 words
- Start with value proposition

For templates, see [templates/](templates/).
```
### Пример 5: Skill для генерации CLAUDE.md
```yaml
---
name: claude-md
description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding.
---

## Core Principles

**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation.

### The Golden Rules

1. **Less is More**: Keep under 300 lines (ideally under 100)
2. **Universal Applicability**: Only include information relevant to EVERY session
3. **Don't Use Claude as a Linter**: Use deterministic tools instead
4. **Never Auto-Generate**: Craft it manually with careful consideration

## Essential Sections

- **Project Name**: Brief one-line description
- **Tech Stack**: Primary language, frameworks, database
- **Development Commands**: Install, test, build commands
- **Critical Conventions**: Only non-obvious, high-impact conventions
- **Known Issues / Gotchas**: Things that trip up developers
```
### Пример 6: Skill для рефакторинга со скриптами

**Структура каталогов:**
```
refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py
```
Текущая дата: вторник, 4 августа 2026 г.

<query>

**Файл:** `refactor/SKILL.md`

</query>
```yaml
---
name: refactor
description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells.
---

# Code Refactoring Skill

A phased approach emphasizing safe, incremental changes backed by tests.

## Workflow

Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment →
Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation →
Phase 5: Incremental Implementation → Phase 6: Review & Iteration

## Core Principles

1. **Behavior Preservation**: External behavior must remain unchanged
2. **Small Steps**: Make tiny, testable changes
3. **Test-Driven**: Tests are the safety net
4. **Continuous**: Refactoring is ongoing, not a one-time event

For code smell catalog, see [references/code-smells.md](references/code-smells.md).
For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md).
```
## Вспомогательные файлы

Помимо `SKILL.md`, skill может содержать в своей директории и другие файлы. Такие вспомогательные файлы (шаблоны, примеры, скрипты, справочные материалы) позволяют не перегружать основной файл skill, предоставляя Claude дополнительные ресурсы, которые он может подгружать по мере необходимости.
```
my-skill/
├── SKILL.md              # Main instructions (required, keep under 500 lines)
├── templates/            # Templates for Claude to fill in
│   └── output-format.md
├── examples/             # Example outputs showing expected format
│   └── sample-output.md
├── references/           # Domain knowledge and specifications
│   └── api-spec.md
└── scripts/              # Scripts Claude can execute
    └── validate.sh
```
Рекомендации по вспомогательным файлам:

- Держите `SKILL.md` в пределах **500 строк**. Выносите подробные справочные материалы, объёмные примеры и спецификации в отдельные файлы.
- Ссылайтесь на дополнительные файлы из `SKILL.md` по **относительным путям** (например, `[справочник по API](references/api-spec.md)`).
- Вспомогательные файлы загружаются на Level 3 (по мере необходимости), поэтому они не расходуют context, пока Claude фактически их не прочитает.

## Управление skills

### Просмотр доступных skills

Спросите Claude напрямую:
```
What Skills are available?
```
Или проверьте файловую систему:
```bash
# List personal Skills
ls ~/.claude/skills/

# List project Skills
ls .claude/skills/
```
> **Совет (v2.1.121+):** начните вводить текст, чтобы отфильтровать интерактивное меню `/skills` - удобно, когда установлено много skills.

### Тестирование skill

Есть два способа:

**Дать Claude вызвать skill автоматически** - задайте вопрос, соответствующий описанию:
```
Can you help me review this code for security issues?
```
**Или вызовите его напрямую**, указав имя skill:
```
/code-review-specialist src/auth/login.ts
```
> **Примечание**: Этот локальный skill устанавливается под именем `code-review-specialist`, чтобы **не** конфликтовать со встроенной командой `/code-review` (это переименованная `/simplify`, появившаяся в Claude Code v2.1.146). Если же скопировать его в `~/.claude/skills/code-review/`, он перекроет встроенную команду - поэтому оставляйте суффикс `-specialist`.

### Обновление skill

Отредактируйте файл `SKILL.md` напрямую. Изменения вступят в силу при следующем запуске Claude Code.
```bash
# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md
```
### Ограничение доступа Claude к skills

Три способа управления тем, какие skills Claude может вызывать:

**Отключить все skills** в `/permissions`:
```
# Add to deny rules:
Skill
```
**Разрешить или запретить определённые skills**:
```
# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)
```
**Скрыть отдельные skills** можно, добавив `disable-model-invocation: true` в их frontmatter.

### Управление поведением переопределения skills (`skillOverrides`)

Когда project skill и user skill имеют одинаковое имя, по умолчанию побеждает project. Настройка `skillOverrides` (v2.1.129+) позволяет изменить это поведение. Добавьте её в `~/.claude/settings.json` или в `.claude/settings.json` проекта:
```json
{
  "skillOverrides": "name-only"
}
```
Допустимые значения:
| Value | Behavior |
|-------|----------|
| `"on"` (default) | A repo skill can override a user skill of the same name. |
| `"off"` | Disable overriding entirely - user skills always win. |
| `"name-only"` | Match overrides only on skill name (ignore description / source). |
| `"user-invocable-only"` | Only user-invocable skills can be overridden - model-invoked skills always come from their original location. |
Полезно, когда командная политика требует, чтобы «пользовательские skills всегда имели приоритет» (`"off"`) или «разрешались только точечные переопределения по имени» (`"name-only"`).

## Лучшие практики

### 1. Делайте описания конкретными

- **Плохо (расплывчато)**: «Помогает с документами»
- **Хорошо (конкретно)**: «Извлекает текст и таблицы из PDF-файлов, заполняет формы, объединяет документы. Используйте при работе с PDF-файлами или когда пользователь упоминает PDF, формы или извлечение данных из документов».

### 2. Делайте skills узкоспециализированными

- Один skill = одна возможность
- ✅ «Заполнение PDF-форм»
- ❌ «Обработка документов» (слишком широко)

### 3. Включайте триггерные термины

Добавляйте в описания ключевые слова, которые встречаются в запросах пользователей:
```yaml
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
```
### 4. Держите SKILL.md в пределах 500 строк

Выносите подробные справочные материалы в отдельные файлы, которые Claude подгружает по мере необходимости.

### 5. Ссылайтесь на вспомогательные файлы
```markdown
## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)
```
### Рекомендации

- Используйте понятные, описательные имена
- Пишите исчерпывающие инструкции
- Добавляйте конкретные примеры
- Объединяйте связанные скрипты и шаблоны в один пакет
- Проверяйте на реальных сценариях
- Документируйте зависимости

### Чего делать не следует

- Не создавайте skills под разовые задачи
- Не дублируйте уже существующую функциональность
- Не делайте skills слишком универсальными
- Не оставляйте поле description пустым
- Не устанавливайте skills из непроверенных источников без предварительного аудита

## Устранение неполадок

### Краткая справка
| Issue | Solution |
|-------|----------|
| Claude doesn't use Skill | Make description more specific with trigger terms |
| Skill file not found | Verify path: `~/.claude/skills/name/SKILL.md` |
| YAML errors | Check `---` markers, indentation, no tabs |
| Skills conflict | Use distinct trigger terms in descriptions |
| Scripts not running | Check permissions: `chmod +x scripts/*.py` |
| Claude doesn't see all skills | Too many skills; check `/context` for warnings |
### Skill не срабатывает

Если Claude не использует ваш skill, когда вы этого ожидаете:

1. Убедитесь, что описание содержит ключевые слова, которые пользователи произнесли бы естественным образом
2. Проверьте, что skill отображается в ответе на вопрос «Какие skills доступны?»
3. Попробуйте переформулировать запрос так, чтобы он соответствовал описанию
4. Вызовите skill напрямую через `/skill-name` для проверки

### Skill срабатывает слишком часто

Если Claude использует ваш skill в нежелательных случаях:

1. Сделайте описание более конкретным
2. Добавьте `disable-model-invocation: true`, чтобы разрешить только ручной вызов

### Claude видит не все skills

Описания skills загружаются в объёме **1% окна контекста** (запасное значение: **8000 символов**). Каждая запись ограничена 250 символами независимо от бюджета. Выполните `/context`, чтобы проверить наличие предупреждений об исключённых skills. Переопределить бюджет можно через переменную окружения `SLASH_COMMAND_TOOL_CHAR_BUDGET`.

## Вопросы безопасности

**Используйте Skills только из доверенных источников.** Skills предоставляют Claude возможности через инструкции и код - вредоносный Skill может заставить Claude вызывать инструменты или выполнять код опасным образом.

**Ключевые аспекты безопасности:**

- **Проводите тщательный аудит**: просматривайте все файлы в директории Skill
- **Внешние источники несут риск**: Skills, загружающие данные с внешних URL, могут быть скомпрометированы
- **Злоупотребление инструментами**: вредоносные Skills могут вызывать инструменты во вред
- **Относитесь к этому как к установке ПО**: используйте Skills только из доверенных источников

### Отключение shell-подстановки в skills

Skills поддерживают синтаксис `` !`command` `` для вставки вывода shell-команд в prompt до того, как его увидит Claude. В окружениях с повышенными требованиями к безопасности (общие корпоративные развёртывания, изолированные CI-раннеры) эту подстановку можно полностью отключить через параметр `disableSkillShellExecution` (добавлен в **v2.1.91**):
```jsonc
// ~/.claude/settings.json or managed policy
{
  "disableSkillShellExecution": true
}
```
Когда `disableSkillShellExecution` установлено в `true`, любые маркеры `` !`command` `` внутри skill остаются литеральным текстом и не выполняются - это убирает поверхность атаки shell-injection на уровне skill, не отключая сами skills. Такую настройку стоит комбинировать с белым списком `allowedTools` для эшелонированной защиты.

### Скрытие встроенных skills (`disableBundledSkills`)

Настройка `disableBundledSkills` (добавлена в **v2.1.169**) скрывает от модели встроенные skills, workflows и команды, поставляемые в комплекте с Claude Code. Используйте её, если встроенные skills создают лишний шум в конкретном проекте или если нужно сократить доступную модели поверхность skills:
```jsonc
// ~/.claude/settings.json or project .claude/settings.json
{
  "disableBundledSkills": true
}
```
Эквивалентная форма через переменную окружения:
```bash
export CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1
```
## Skills и другие возможности
| Feature | Invocation | Best For |
|---------|------------|----------|
| **Skills** | Auto or `/name` | Reusable expertise, workflows |
| **Slash Commands** | User-initiated `/name` | Quick shortcuts (merged into skills) |
| **Subagents** | Auto-delegated | Isolated task execution |
| **Memory (CLAUDE.md)** | Always loaded | Persistent project context |
| **MCP** | Real-time | External data/service access |
| **Hooks** | Event-driven | Automated side effects |
## Встроенные skills

В комплект Claude Code входит набор встроенных skills, доступных сразу без установки (наиболее полезные перечислены ниже; полный список см. в [справочнике команд](https://code.claude.com/docs/en/commands)):
| Skill | Description |
|-------|-------------|
| `/batch <instruction>` | Orchestrate large-scale parallel changes across codebase using git worktrees |
| `/claude-api` | Load Claude API/SDK reference; auto-activates on `anthropic`/`@anthropic-ai/sdk` imports |
| `/dataviz` | Chart and dashboard design guidance with a runnable color-palette validator (v2.1.198) |
| `/debug [description]` | Troubleshoot current session by reading debug log |
| `/deep-research <topic>` | Run an in-depth research pass on a topic (explicit invocation only since v2.1.218 - Claude won't trigger this on its own) |
| `/fewer-permission-prompts` | Scan transcripts and propose a prioritized allowlist for common read-only tools |
| `/loop [interval] <prompt>` | Run prompt repeatedly on interval (e.g., `/loop 5m check the deploy`) |
| `/run` *(v2.1.145+)* | Launch this project's app to see a change running - looks for a project skill, otherwise falls back to built-in patterns per project type |
| `/run-skill-generator` *(v2.1.145+)* | Teach `/run`/`/verify` how to handle a specific project by generating a per-project skill |
| `/code-review [effort]` | Review the current diff for correctness bugs at a chosen effort level (e.g. `/code-review high`); pass `--comment` to post findings as inline PR comments. A distinct skill from `/simplify` (quality/reuse cleanups), which was split back out in v2.1.154. (explicit invocation only since v2.1.215 - Claude won't trigger this on its own) Since v2.1.218 it runs as a background subagent, so review work no longer fills your conversation and stacked slash commands stay its review target. |
| `/simplify` | Cleanup-only review - reuse, simplification, efficiency, altitude - and applies the fixes. Split back out from `/code-review` in v2.1.154 |
| `/verify` *(v2.1.145+)* | Build, run, and observe the app to confirm a fix works (not just that tests pass) (explicit invocation only since v2.1.215 - Claude won't trigger this on its own) |
Эти skills доступны из коробки и не требуют установки или настройки. Они используют тот же формат SKILL.md, что и пользовательские skills.

## Совместное использование Skills

### Проектные Skills (общие для команды)

1. Создайте Skill в `.claude/skills/`
2. Закоммитьте в git
3. Участники команды делают pull изменений - Skills сразу доступны

### Личные Skills
```bash
# Copy to personal directory
cp -r my-skill ~/.claude/skills/

# Make scripts executable
chmod +x ~/.claude/skills/my-skill/scripts/*.py
```
### Распространение через плагины

Упаковывайте skills в директорию `skills/` плагина для более широкого распространения.

## Что дальше: коллекция skills и менеджер skills

Когда вы всерьёз возьмётесь за создание skills, вам понадобятся две вещи: библиотека проверенных skills и инструмент для управления ими.

**[luongnv89/skills](https://github.com/luongnv89/skills)** - коллекция skills, которые я ежедневно использую почти во всех своих проектах. Из наиболее интересных стоит отметить `logo-designer` (на лету генерирует логотипы проектов) и `ollama-optimizer` (подстраивает производительность локальных LLM под ваше железо). Отличная отправная точка, если вам нужны готовые к использованию skills.

**[luongnv89/asm](https://github.com/luongnv89/asm)** - Agent Skill Manager. Отвечает за разработку skills, обнаружение дубликатов и тестирование. Команда `asm link` позволяет тестировать skill в любом проекте без копирования файлов - незаменимая вещь, когда skills становится больше нескольких штук.

## Дополнительные материалы

- [Официальная документация по skills](https://code.claude.com/docs/en/skills)
- [Статья в блоге об архитектуре Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills)
- [Репозиторий skills](https://github.com/luongnv89/skills) - коллекция готовых к использованию skills
- [Руководство по slash-командам](../01-slash-commands/) - сокращения, запускаемые пользователем
- [Руководство по subagents](../04-subagents/) - делегируемые AI-агенты
- [Руководство по memory](../02-memory/) - постоянный контекст
- [MCP (Model Context Protocol)](../05-mcp/) - внешние данные в реальном времени
- [Руководство по hooks](../06-hooks/) - автоматизация на основе событий

---

**Последнее обновление**: 4 августа 2026 г.
**Версия Claude Code**: 2.1.220
**Источники**:
- https://code.claude.com/docs/en/skills
- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
- https://code.claude.com/docs/en/model-config
**Совместимые модели**: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5