МОДУЛЬ 03/УРОК

Навыки (Skills)

Руководство по Agent Skills

Agent Skills - это переиспользуемые возможности на основе файловой системы, расширяющие функциональность Claude. Они упаковывают предметную экспертизу, рабочие процессы и лучшие практики в обнаруживаемые компоненты, которые Claude автоматически задействует, когда это уместно.

Обзор

Agent Skills - это модульные возможности, превращающие универсальных агентов в узких специалистов. В отличие от промптов (инструкций уровня диалога для разовых задач), skills загружаются по требованию и избавляют от необходимости повторять одни и те же указания в разных диалогах.

Ключевые преимущества

  • Специализация Claude: адаптация возможностей под задачи конкретной предметной области
  • Меньше повторов: создайте один раз - используйте автоматически во всех диалогах
  • Композиция возможностей: объединяйте skills для построения сложных рабочих процессов
  • Масштабирование процессов: переиспользуйте skills в разных проектах и командах
  • Контроль качества: встраивайте лучшие практики непосредственно в рабочий процесс

Skills следуют открытому стандарту Agent Skills, который поддерживается разными AI-инструментами. Claude Code расширяет этот стандарт дополнительными возможностями: управлением вызовом (invocation), запуском в subagent и динамическим внедрением контекста.

Примечание: пользовательские slash-команды объединены со skills. Файлы .claude/commands/ продолжают работать и поддерживают те же поля frontmatter. Для новой разработки рекомендуются skills. Если по одному и тому же пути существуют оба варианта (например, .claude/commands/review.md и .claude/skills/review/SKILL.md), приоритет отдаётся skill.

Как работают Skills: прогрессивное раскрытие

Skills построены на архитектуре прогрессивного раскрытия (progressive disclosure): Claude подгружает информацию поэтапно по мере необходимости, а не загружает весь контекст сразу. Это обеспечивает эффективное управление контекстом при практически неограниченной масштабируемости.

Три уровня загрузки

graph TB subgraph "Level 1: Metadata (Always Loaded)" A["YAML Frontmatter"] A1["~100 tokens per skill"] A2["name + description"] end subgraph "Level 2: Instructions (When Triggered)" B["SKILL.md Body"] B1["Under 5k tokens"] B2["Workflows & guidance"] end subgraph "Level 3: Resources (As Needed)" C["Bundled Files"] C1["Effectively unlimited"] C2["Scripts, templates, docs"] end A --> B B --> C
LevelWhen LoadedToken CostContent
Level 1: MetadataAlways (at startup)~100 tokens per Skillname and description from YAML frontmatter
Level 2: InstructionsWhen Skill is triggeredUnder 5k tokensSKILL.md body with instructions and guidance
Level 3+: ResourcesAs neededEffectively unlimitedBundled files executed via bash without loading contents into context
Это означает, что можно установить множество Skills без ущерба для контекста - до момента фактического вызова Claude знает лишь о том, что каждый Skill существует и когда его следует применять.

Процесс загрузки Skill

sequenceDiagram participant User participant Claude participant System participant SkillInst as Skill Instructions participant SkillRes as Skill Resources User->>Claude: "Review this code for security issues" Claude->>System: Check available skills (metadata) System-->>Claude: Skill descriptions loaded at startup Claude->>Claude: Match request to skill description Claude->>SkillInst: Read code-review-specialist/SKILL.md SkillInst-->>Claude: Level 2: Instructions loaded Claude->>Claude: Determine: Need templates? Claude->>SkillRes: Read templates/checklist.md SkillRes-->>Claude: Level 3: Template loaded Claude->>Claude: Execute skill instructions Claude->>User: Comprehensive code review

Типы skills и их расположение

TypeLocationScopeSharedBest For
EnterpriseManaged settingsAll org usersYesOrganization-wide standards
Personal~/.claude/skills/<skill-name>/SKILL.mdIndividualNoPersonal workflows
Project.claude/skills/<skill-name>/SKILL.mdTeamYes (via git)Team standards
Plugin<plugin>/skills/<skill-name>/SKILL.mdWhere enabledDependsBundled with plugins
Когда skills имеют одинаковое имя на разных уровнях, побеждают расположения с более высоким приоритетом: enterprise > personal > project. По умолчанию personal skills переопределяют project skills; настройка skillOverrides (v2.1.129+) позволяет изменить это поведение - см. Управление поведением переопределения skill. Plugin skills используют пространство имён plugin-name:skill-name, поэтому не могут конфликтовать.

Обнаружение skills субагентами (v2.1.133+): теперь субагенты обнаруживают project, user и plugin skills через инструмент Skill так же, как и основная сессия. В более ранних версиях субагенты были ограничены собственным встроенным набором, из-за чего связки skill+subagent незаметно ломались; начиная с v2.1.133 обеим сторонам виден один и тот же каталог skills.

Автоматическое обнаружение

Вложенные директории: когда вы работаете с файлами в поддиректориях, Claude Code автоматически обнаруживает skills во вложенных директориях .claude/skills/. Например, если вы редактируете файл в packages/frontend/, Claude Code также ищет skills в packages/frontend/.claude/skills/. Это удобно для monorepo, где у каждого пакета есть собственные skills. Начиная с v2.1.178, при коллизии имён skill между вложенными директориями .claude/skills/ побеждает директория, ближайшая к текущей рабочей директории - skill уровня пакета переопределяет одноимённый skill из корня репозитория.

Директории --add-dir: skills из директорий, добавленных через --add-dir, загружаются автоматически, с отслеживанием изменений «на лету». Любые правки файлов skill в этих директориях вступают в силу немедленно, без перезапуска Claude Code.

Перезагрузка skills: команда /reload-skills (добавлена в v2.1.152) заново сканирует все директории skill без перезапуска сессии - полезно после добавления или редактирования skill, который не был подхвачен автоматическим отслеживанием. Такое же повторное сканирование можно запустить из hook SessionStart, вернув reloadSkills: true (см. Hooks).

Бюджет описаний: описания skill (метаданные Level 1) ограничены 1% контекстного окна (по умолчанию: 8000 символов). Если установлено много skills, описания могут быть сокращены. Имена skill включаются всегда, а описания обрезаются под лимит. Выносите ключевой сценарий использования в начало описания. Изменить бюджет можно через переменную окружения SLASH_COMMAND_TOOL_CHAR_BUDGET.

Создание собственных skills

Базовая структура директорий

CODE
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

Формат SKILL.md

yaml
---
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.

Рекомендуемые поля

  • description (рекомендуется): что делает skill И когда его использовать. Если поле опущено, Claude Code берёт первый абзац Markdown-содержимого. Объединённый текст description + when_to_use обрезается до 1536 символов в списке skill'ов (настраивается через skillListingMaxDescChars). Именно по этому тексту Claude определяет, когда активировать skill.
  • name (необязательно): по умолчанию совпадает с именем директории skill'а. Если указано явно, задаёт отображаемое имя - допустимы только строчные буквы, цифры и дефисы (не более 64 символов); значение не должно содержать "anthropic" или "claude". Для skill'ов из плагинов name также задаёт последний сегмент имени команды.

Все поля frontmatter в SKILL.md опциональны; рекомендуется указывать только description.

Необязательные поля frontmatter

yaml
---
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
---
FieldDescription
nameLowercase letters, numbers, hyphens only (max 64 chars). Cannot contain "anthropic" or "claude".
descriptionWhat the Skill does AND when to use it. The combined description + when_to_use text is truncated at 1,536 chars in the skill listing (configurable via skillListingMaxDescChars). Critical for auto-invocation matching.
when_to_useAdditional context for when Claude should invoke the skill. Appended to description in the skill listing and counts toward the 1,536-character cap.
argument-hintHint shown in the / autocomplete menu (e.g., "[filename] [format]").
disable-model-invocationtrue = only the user can invoke via /name. Claude will never auto-invoke.
user-invocablefalse = hidden from the / menu. Only Claude can invoke it automatically.
allowed-toolsComma-separated list of tools the skill may use without permission prompts.
disallowed-toolsComma-separated list of tools to remove while the skill is active (complements allowed-tools). Added v2.1.152.
modelModel override while the skill is active (e.g., opus, sonnet).
effortEffort level override while the skill is active: low, medium, high, xhigh, or max - all five are supported on Opus 5, Sonnet 5, Opus 4.8, and Opus 4.7. The default effort is high on every model that supports effort, except Opus 4.7 which defaults to xhigh.
contextfork to run the skill in a forked subagent context with its own context window.
agentSubagent type when context: fork (e.g., Explore, Plan, general-purpose).
backgroundOnly meaningful with context: fork. Defaults to true for context: fork skills, so they run in the background; set false to run them in the foreground. Added v2.1.218.
shellShell used for !`command` substitutions and scripts: bash (default) or powershell.
hooksHooks scoped to this skill's lifecycle (same format as global hooks).
pathsGlob patterns that limit when the skill is auto-activated. Comma-separated string or YAML list. Same format as path-specific rules.
argumentsDeclares the arguments the skill accepts, for autocomplete and argument substitution.
metadataFree-form key/value map for your own bookkeeping (e.g. version, author). Claude Code passes it through.
licenseLicense identifier for the skill (e.g. MIT).
compatibilityFree-text compatibility statement, up to 500 characters. Claude Code accepts it but does not act on it.

Примечание: Для skills, загруженных на claude.ai или созданных через Skills API, допустимы только поля name, description, license, compatibility, metadata и allowed-tools. Остальные поля в этой таблице специфичны для Claude Code.

Начиная с v2.1.218, булевы поля во frontmatter также принимают значения yes/no, on/off и 1/0 (без учёта регистра) в дополнение к true/false.

Типы содержимого skill

Skill может содержать два типа контента, каждый из которых предназначен для своих задач:

Справочный контент

Добавляет знания, которые Claude применяет к вашей текущей работе, - соглашения, паттерны, style guides, знания предметной области. Загружается непосредственно в контекст вашей беседы.

yaml
---
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

Содержимое задачи

Пошаговые инструкции для конкретных действий. Часто вызываются напрямую командой /skill-name.

yaml
---
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

Управление вызовом skill

По умолчанию как вы, так и Claude можете вызвать любой skill. За три режима вызова отвечают два поля во frontmatter:

FrontmatterYou can invokeClaude can invoke
(default)YesYes
disable-model-invocation: trueYesNo
user-invocable: falseNoYes
Используйте disable-model-invocation: true для workflow с побочными эффектами: /commit, /deploy, /send-slack-message. Вряд ли вам хочется, чтобы Claude сам решал выполнить deploy только потому, что код выглядит готовым.

Используйте user-invocable: false для справочных знаний, которые не подразумевают выполнения как команды. Skill legacy-system-context описывает устройство устаревшей системы - это полезно для Claude, но не является осмысленным действием со стороны пользователя.

Подстановка строк

Skills поддерживают динамические значения, которые подставляются ещё до того, как содержимое skill попадёт к Claude:

VariableDescription
$ARGUMENTSAll arguments passed when invoking the skill
$ARGUMENTS[N] or $NAccess specific argument by index (0-based)
${CLAUDE_SESSION_ID}Current session ID
${CLAUDE_SKILL_DIR}Directory containing the skill's SKILL.md file
${CLAUDE_PROJECT_DIR}Absolute path to the project root. Usable in the skill body and in allowed-tools (v2.1.196)
${CLAUDE_EFFORT}Current effort level (low, medium, high, xhigh, or max). Useful for branching skill behavior: e.g., [ "${CLAUDE_EFFORT}" = "max" ] && deep_analysis (v2.1.120+)
!`command`Dynamic context injection - runs a shell command and inlines the output
Пример:
yaml
---
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

Вызов /fix-issue 123 подставляет 123 вместо $ARGUMENTS.

Стекирование skills

Slash-skills можно стекировать в рамках одного вызова, например /code-review /fix-issue 123. Начиная с v2.1.199, загружаются ВСЕ идущие подряд в начале skills - первый и ещё до 5 дополнительных, - а замыкающие аргументы (123) передаются каждому из них; раньше загружался только первый skill. Если один и тот же skill указан несколько раз, его идентичное содержимое дедуплицируется (v2.1.202), а не добавляется повторно.

Подстановка динамического контекста

Синтаксис !`command` выполняет shell-команды до того, как содержимое skill будет отправлено Claude:

yaml
---
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...

Команды выполняются немедленно; Claude видит только итоговый вывод. По умолчанию команды запускаются в bash. Чтобы вместо этого использовать PowerShell, укажите shell: powershell во frontmatter.

Запуск skills в субагентах

Добавьте context: fork, чтобы запустить skill в изолированном контексте субагента. Содержимое skill становится задачей для отдельного субагента с собственным контекстным окном, благодаря чему основной диалог не засоряется. Начиная с v2.1.218, для skills с context: fork параметр background по умолчанию равен true, то есть они выполняются в фоне; чтобы запустить fork-skill на переднем плане, укажите background: false во frontmatter.

Исправление в v2.1.145: ранее skill с context: fork в редких случаях мог приводить к бесконечному циклу повторных вызовов. Если вы разрабатываете fork-skills или полагаетесь на них, обновитесь до v2.1.145 или новее.

Поле agent задаёт тип используемого агента:

Agent TypeBest For
ExploreRead-only research, codebase analysis
PlanCreating implementation plans
general-purposeBroad tasks requiring all tools
Custom agentsSpecialized agents defined in your configuration
Пример frontmatter:
yaml
---
context: fork
agent: Explore
---

Полный пример skill:

yaml
---
name: topic-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

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

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

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

CODE
~/.claude/skills/code-review-specialist/
├── SKILL.md
├── templates/
│   ├── review-checklist.md
│   └── finding-template.md
└── scripts/
    ├── analyze-metrics.py
    └── compare-complexity.py

Файл: ~/.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).

Пример 2: Skill для визуализации кодовой базы

Skill, генерирующий интерактивные HTML-визуализации:

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

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

Файл: ~/.claude/skills/codebase-visualizer/SKILL.md

yaml
---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python *)
---

# Codebase Visualizer

Generate an interactive HTML tree view showing your project's file structure.

## Usage

Run the visualization script from your project root:

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

This creates `codebase-map.html` and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

Встроенный 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 для рефакторинга со скриптами

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

CODE
refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py

Текущая дата: воскресенье, 6 сентября 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. For refactoring techniques, see references/refactoring-catalog.md.

CODE
## Вспомогательные файлы

В директории skill, помимо `SKILL.md`, можно размещать и другие файлы. Такие вспомогательные файлы (шаблоны, примеры, скрипты, справочные материалы) позволяют не перегружать основной файл 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

CODE
Рекомендации по вспомогательным файлам:

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

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

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

Спросите Claude напрямую:

What Skills are available?

CODE
Или проверьте файловую систему:
```bash
# List personal Skills
ls ~/.claude/skills/

# List project Skills
ls .claude/skills/

Совет (v2.1.121+): введите текст для фильтрации интерактивного меню /skills - удобно, когда установлено много skills.

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

Есть два способа протестировать:

Дайте Claude вызвать skill автоматически - сформулируйте запрос, соответствующий описанию:

CODE
Can you help me review this code for security issues?

Или вызовите его напрямую, указав имя skill:

CODE
/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 напрямую, а затем выполните /reload-skills (v2.1.152+), чтобы повторно просканировать директории со skills. Перезапуск Claude Code тоже подойдёт, но не обязателен - skills из директорий, указанных в --add-dir, подхватываются на лету, а hook SessionStart, возвращающий reloadSkills: true, запускает такое же повторное сканирование.

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:

CODE
# Add to deny rules:
Skill

Разрешить или запретить определённые skills:

CODE
# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Скрыть отдельные skill можно, добавив disable-model-invocation: true в их frontmatter.

Управление переопределением skill (skillOverrides)

Если skill проекта и skill пользователя имеют одинаковое имя, по умолчанию приоритет отдаётся проекту. Настройка skillOverrides (v2.1.129+) позволяет изменить это поведение. Добавьте её в ~/.claude/settings.json или в проектный .claude/settings.json:

json
{
  "skillOverrides": "name-only"
}

Допустимые значения:

ValueBehavior
"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 из непроверенных источников без аудита

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

Краткий справочник

IssueSolution
Claude doesn't use SkillMake description more specific with trigger terms
Skill file not foundVerify path: ~/.claude/skills/name/SKILL.md
YAML errorsCheck --- markers, indentation, no tabs
Skills conflictUse distinct trigger terms in descriptions
Scripts not runningCheck permissions: chmod +x scripts/*.py
Claude doesn't see all skillsToo many skills; check /context for warnings, then run /skill-doctor (v2.1.252+) to see which skills go unused and what they cost

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% окна контекста (значение по умолчанию: 8 000 символов). Каждая запись ограничена 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 и другие возможности

FeatureInvocationBest For
SkillsAuto or /nameReusable expertise, workflows
Slash CommandsUser-initiated /nameQuick shortcuts (merged into skills)
SubagentsAuto-delegatedIsolated task execution
Memory (CLAUDE.md)Always loadedPersistent project context
MCPReal-timeExternal data/service access
HooksEvent-drivenAutomated side effects

Встроенные skills

Claude Code поставляется со встроенным набором skills, которые всегда доступны без установки (наиболее полезные из них перечислены ниже; полный список см. в справочнике по commands):

SkillDescription
/batch <instruction>Orchestrate large-scale parallel changes across codebase using git worktrees
/claude-apiLoad Claude API/SDK reference; auto-activates on anthropic/@anthropic-ai/sdk imports
/datavizChart 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-promptsScan 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.
/simplifyCleanup-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 - коллекция skills, которые я использую ежедневно практически во всех своих проектах. Среди самых примечательных - logo-designer (на лету генерирует логотипы проектов) и ollama-optimizer (подстраивает производительность локальной LLM под ваше железо). Отличная отправная точка, если нужны готовые к использованию skills.

luongnv89/asm - Agent Skill Manager. Берёт на себя разработку skills, поиск дубликатов и тестирование. Команда asm link позволяет протестировать skill в любом проекте без копирования файлов - незаменимая вещь, когда skills у вас накопилось больше пары штук.

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


Последнее обновление: 6 сентября 2026 г. Версия Claude Code: 2.1.263 Источники:

ЛОКАЛЬНАЯ ОТМЕТКА · БЕЗ ПРОВЕРКИ
cc-learnМОДУЛЬ 03
МОДУЛЬ 03/УРОК

Навыки (Skills)

Руководство по Agent Skills

Agent Skills - это переиспользуемые возможности на основе файловой системы, расширяющие функциональность Claude. Они упаковывают предметную экспертизу, рабочие процессы и лучшие практики в обнаруживаемые компоненты, которые Claude автоматически задействует, когда это уместно.

Обзор

Agent Skills - это модульные возможности, превращающие универсальных агентов в узких специалистов. В отличие от промптов (инструкций уровня диалога для разовых задач), skills загружаются по требованию и избавляют от необходимости повторять одни и те же указания в разных диалогах.

Ключевые преимущества

  • Специализация Claude: адаптация возможностей под задачи конкретной предметной области
  • Меньше повторов: создайте один раз - используйте автоматически во всех диалогах
  • Композиция возможностей: объединяйте skills для построения сложных рабочих процессов
  • Масштабирование процессов: переиспользуйте skills в разных проектах и командах
  • Контроль качества: встраивайте лучшие практики непосредственно в рабочий процесс

Skills следуют открытому стандарту Agent Skills, который поддерживается разными AI-инструментами. Claude Code расширяет этот стандарт дополнительными возможностями: управлением вызовом (invocation), запуском в subagent и динамическим внедрением контекста.

Примечание: пользовательские slash-команды объединены со skills. Файлы .claude/commands/ продолжают работать и поддерживают те же поля frontmatter. Для новой разработки рекомендуются skills. Если по одному и тому же пути существуют оба варианта (например, .claude/commands/review.md и .claude/skills/review/SKILL.md), приоритет отдаётся skill.

Как работают Skills: прогрессивное раскрытие

Skills построены на архитектуре прогрессивного раскрытия (progressive disclosure): Claude подгружает информацию поэтапно по мере необходимости, а не загружает весь контекст сразу. Это обеспечивает эффективное управление контекстом при практически неограниченной масштабируемости.

Три уровня загрузки

graph TB subgraph "Level 1: Metadata (Always Loaded)" A["YAML Frontmatter"] A1["~100 tokens per skill"] A2["name + description"] end subgraph "Level 2: Instructions (When Triggered)" B["SKILL.md Body"] B1["Under 5k tokens"] B2["Workflows & guidance"] end subgraph "Level 3: Resources (As Needed)" C["Bundled Files"] C1["Effectively unlimited"] C2["Scripts, templates, docs"] end A --> B B --> C
LevelWhen LoadedToken CostContent
Level 1: MetadataAlways (at startup)~100 tokens per Skillname and description from YAML frontmatter
Level 2: InstructionsWhen Skill is triggeredUnder 5k tokensSKILL.md body with instructions and guidance
Level 3+: ResourcesAs neededEffectively unlimitedBundled files executed via bash without loading contents into context
Это означает, что можно установить множество Skills без ущерба для контекста - до момента фактического вызова Claude знает лишь о том, что каждый Skill существует и когда его следует применять.

Процесс загрузки Skill

sequenceDiagram participant User participant Claude participant System participant SkillInst as Skill Instructions participant SkillRes as Skill Resources User->>Claude: "Review this code for security issues" Claude->>System: Check available skills (metadata) System-->>Claude: Skill descriptions loaded at startup Claude->>Claude: Match request to skill description Claude->>SkillInst: Read code-review-specialist/SKILL.md SkillInst-->>Claude: Level 2: Instructions loaded Claude->>Claude: Determine: Need templates? Claude->>SkillRes: Read templates/checklist.md SkillRes-->>Claude: Level 3: Template loaded Claude->>Claude: Execute skill instructions Claude->>User: Comprehensive code review

Типы skills и их расположение

TypeLocationScopeSharedBest For
EnterpriseManaged settingsAll org usersYesOrganization-wide standards
Personal~/.claude/skills/<skill-name>/SKILL.mdIndividualNoPersonal workflows
Project.claude/skills/<skill-name>/SKILL.mdTeamYes (via git)Team standards
Plugin<plugin>/skills/<skill-name>/SKILL.mdWhere enabledDependsBundled with plugins
Когда skills имеют одинаковое имя на разных уровнях, побеждают расположения с более высоким приоритетом: enterprise > personal > project. По умолчанию personal skills переопределяют project skills; настройка skillOverrides (v2.1.129+) позволяет изменить это поведение - см. Управление поведением переопределения skill. Plugin skills используют пространство имён plugin-name:skill-name, поэтому не могут конфликтовать.

Обнаружение skills субагентами (v2.1.133+): теперь субагенты обнаруживают project, user и plugin skills через инструмент Skill так же, как и основная сессия. В более ранних версиях субагенты были ограничены собственным встроенным набором, из-за чего связки skill+subagent незаметно ломались; начиная с v2.1.133 обеим сторонам виден один и тот же каталог skills.

Автоматическое обнаружение

Вложенные директории: когда вы работаете с файлами в поддиректориях, Claude Code автоматически обнаруживает skills во вложенных директориях .claude/skills/. Например, если вы редактируете файл в packages/frontend/, Claude Code также ищет skills в packages/frontend/.claude/skills/. Это удобно для monorepo, где у каждого пакета есть собственные skills. Начиная с v2.1.178, при коллизии имён skill между вложенными директориями .claude/skills/ побеждает директория, ближайшая к текущей рабочей директории - skill уровня пакета переопределяет одноимённый skill из корня репозитория.

Директории --add-dir: skills из директорий, добавленных через --add-dir, загружаются автоматически, с отслеживанием изменений «на лету». Любые правки файлов skill в этих директориях вступают в силу немедленно, без перезапуска Claude Code.

Перезагрузка skills: команда /reload-skills (добавлена в v2.1.152) заново сканирует все директории skill без перезапуска сессии - полезно после добавления или редактирования skill, который не был подхвачен автоматическим отслеживанием. Такое же повторное сканирование можно запустить из hook SessionStart, вернув reloadSkills: true (см. Hooks).

Бюджет описаний: описания skill (метаданные Level 1) ограничены 1% контекстного окна (по умолчанию: 8000 символов). Если установлено много skills, описания могут быть сокращены. Имена skill включаются всегда, а описания обрезаются под лимит. Выносите ключевой сценарий использования в начало описания. Изменить бюджет можно через переменную окружения SLASH_COMMAND_TOOL_CHAR_BUDGET.

Создание собственных skills

Базовая структура директорий

CODE
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

Формат SKILL.md

yaml
---
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.

Рекомендуемые поля

  • description (рекомендуется): что делает skill И когда его использовать. Если поле опущено, Claude Code берёт первый абзац Markdown-содержимого. Объединённый текст description + when_to_use обрезается до 1536 символов в списке skill'ов (настраивается через skillListingMaxDescChars). Именно по этому тексту Claude определяет, когда активировать skill.
  • name (необязательно): по умолчанию совпадает с именем директории skill'а. Если указано явно, задаёт отображаемое имя - допустимы только строчные буквы, цифры и дефисы (не более 64 символов); значение не должно содержать "anthropic" или "claude". Для skill'ов из плагинов name также задаёт последний сегмент имени команды.

Все поля frontmatter в SKILL.md опциональны; рекомендуется указывать только description.

Необязательные поля frontmatter

yaml
---
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
---
FieldDescription
nameLowercase letters, numbers, hyphens only (max 64 chars). Cannot contain "anthropic" or "claude".
descriptionWhat the Skill does AND when to use it. The combined description + when_to_use text is truncated at 1,536 chars in the skill listing (configurable via skillListingMaxDescChars). Critical for auto-invocation matching.
when_to_useAdditional context for when Claude should invoke the skill. Appended to description in the skill listing and counts toward the 1,536-character cap.
argument-hintHint shown in the / autocomplete menu (e.g., "[filename] [format]").
disable-model-invocationtrue = only the user can invoke via /name. Claude will never auto-invoke.
user-invocablefalse = hidden from the / menu. Only Claude can invoke it automatically.
allowed-toolsComma-separated list of tools the skill may use without permission prompts.
disallowed-toolsComma-separated list of tools to remove while the skill is active (complements allowed-tools). Added v2.1.152.
modelModel override while the skill is active (e.g., opus, sonnet).
effortEffort level override while the skill is active: low, medium, high, xhigh, or max - all five are supported on Opus 5, Sonnet 5, Opus 4.8, and Opus 4.7. The default effort is high on every model that supports effort, except Opus 4.7 which defaults to xhigh.
contextfork to run the skill in a forked subagent context with its own context window.
agentSubagent type when context: fork (e.g., Explore, Plan, general-purpose).
backgroundOnly meaningful with context: fork. Defaults to true for context: fork skills, so they run in the background; set false to run them in the foreground. Added v2.1.218.
shellShell used for !`command` substitutions and scripts: bash (default) or powershell.
hooksHooks scoped to this skill's lifecycle (same format as global hooks).
pathsGlob patterns that limit when the skill is auto-activated. Comma-separated string or YAML list. Same format as path-specific rules.
argumentsDeclares the arguments the skill accepts, for autocomplete and argument substitution.
metadataFree-form key/value map for your own bookkeeping (e.g. version, author). Claude Code passes it through.
licenseLicense identifier for the skill (e.g. MIT).
compatibilityFree-text compatibility statement, up to 500 characters. Claude Code accepts it but does not act on it.

Примечание: Для skills, загруженных на claude.ai или созданных через Skills API, допустимы только поля name, description, license, compatibility, metadata и allowed-tools. Остальные поля в этой таблице специфичны для Claude Code.

Начиная с v2.1.218, булевы поля во frontmatter также принимают значения yes/no, on/off и 1/0 (без учёта регистра) в дополнение к true/false.

Типы содержимого skill

Skill может содержать два типа контента, каждый из которых предназначен для своих задач:

Справочный контент

Добавляет знания, которые Claude применяет к вашей текущей работе, - соглашения, паттерны, style guides, знания предметной области. Загружается непосредственно в контекст вашей беседы.

yaml
---
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

Содержимое задачи

Пошаговые инструкции для конкретных действий. Часто вызываются напрямую командой /skill-name.

yaml
---
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

Управление вызовом skill

По умолчанию как вы, так и Claude можете вызвать любой skill. За три режима вызова отвечают два поля во frontmatter:

FrontmatterYou can invokeClaude can invoke
(default)YesYes
disable-model-invocation: trueYesNo
user-invocable: falseNoYes
Используйте disable-model-invocation: true для workflow с побочными эффектами: /commit, /deploy, /send-slack-message. Вряд ли вам хочется, чтобы Claude сам решал выполнить deploy только потому, что код выглядит готовым.

Используйте user-invocable: false для справочных знаний, которые не подразумевают выполнения как команды. Skill legacy-system-context описывает устройство устаревшей системы - это полезно для Claude, но не является осмысленным действием со стороны пользователя.

Подстановка строк

Skills поддерживают динамические значения, которые подставляются ещё до того, как содержимое skill попадёт к Claude:

VariableDescription
$ARGUMENTSAll arguments passed when invoking the skill
$ARGUMENTS[N] or $NAccess specific argument by index (0-based)
${CLAUDE_SESSION_ID}Current session ID
${CLAUDE_SKILL_DIR}Directory containing the skill's SKILL.md file
${CLAUDE_PROJECT_DIR}Absolute path to the project root. Usable in the skill body and in allowed-tools (v2.1.196)
${CLAUDE_EFFORT}Current effort level (low, medium, high, xhigh, or max). Useful for branching skill behavior: e.g., [ "${CLAUDE_EFFORT}" = "max" ] && deep_analysis (v2.1.120+)
!`command`Dynamic context injection - runs a shell command and inlines the output
Пример:
yaml
---
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

Вызов /fix-issue 123 подставляет 123 вместо $ARGUMENTS.

Стекирование skills

Slash-skills можно стекировать в рамках одного вызова, например /code-review /fix-issue 123. Начиная с v2.1.199, загружаются ВСЕ идущие подряд в начале skills - первый и ещё до 5 дополнительных, - а замыкающие аргументы (123) передаются каждому из них; раньше загружался только первый skill. Если один и тот же skill указан несколько раз, его идентичное содержимое дедуплицируется (v2.1.202), а не добавляется повторно.

Подстановка динамического контекста

Синтаксис !`command` выполняет shell-команды до того, как содержимое skill будет отправлено Claude:

yaml
---
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...

Команды выполняются немедленно; Claude видит только итоговый вывод. По умолчанию команды запускаются в bash. Чтобы вместо этого использовать PowerShell, укажите shell: powershell во frontmatter.

Запуск skills в субагентах

Добавьте context: fork, чтобы запустить skill в изолированном контексте субагента. Содержимое skill становится задачей для отдельного субагента с собственным контекстным окном, благодаря чему основной диалог не засоряется. Начиная с v2.1.218, для skills с context: fork параметр background по умолчанию равен true, то есть они выполняются в фоне; чтобы запустить fork-skill на переднем плане, укажите background: false во frontmatter.

Исправление в v2.1.145: ранее skill с context: fork в редких случаях мог приводить к бесконечному циклу повторных вызовов. Если вы разрабатываете fork-skills или полагаетесь на них, обновитесь до v2.1.145 или новее.

Поле agent задаёт тип используемого агента:

Agent TypeBest For
ExploreRead-only research, codebase analysis
PlanCreating implementation plans
general-purposeBroad tasks requiring all tools
Custom agentsSpecialized agents defined in your configuration
Пример frontmatter:
yaml
---
context: fork
agent: Explore
---

Полный пример skill:

yaml
---
name: topic-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

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

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

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

CODE
~/.claude/skills/code-review-specialist/
├── SKILL.md
├── templates/
│   ├── review-checklist.md
│   └── finding-template.md
└── scripts/
    ├── analyze-metrics.py
    └── compare-complexity.py

Файл: ~/.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).

Пример 2: Skill для визуализации кодовой базы

Skill, генерирующий интерактивные HTML-визуализации:

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

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

Файл: ~/.claude/skills/codebase-visualizer/SKILL.md

yaml
---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python *)
---

# Codebase Visualizer

Generate an interactive HTML tree view showing your project's file structure.

## Usage

Run the visualization script from your project root:

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

This creates `codebase-map.html` and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

Встроенный 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 для рефакторинга со скриптами

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

CODE
refactor/
├── SKILL.md
├── references/
│   ├── code-smells.md
│   └── refactoring-catalog.md
├── templates/
│   └── refactoring-plan.md
└── scripts/
    ├── analyze-complexity.py
    └── detect-smells.py

Текущая дата: воскресенье, 6 сентября 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. For refactoring techniques, see references/refactoring-catalog.md.

CODE
## Вспомогательные файлы

В директории skill, помимо `SKILL.md`, можно размещать и другие файлы. Такие вспомогательные файлы (шаблоны, примеры, скрипты, справочные материалы) позволяют не перегружать основной файл 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

CODE
Рекомендации по вспомогательным файлам:

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

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

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

Спросите Claude напрямую:

What Skills are available?

CODE
Или проверьте файловую систему:
```bash
# List personal Skills
ls ~/.claude/skills/

# List project Skills
ls .claude/skills/

Совет (v2.1.121+): введите текст для фильтрации интерактивного меню /skills - удобно, когда установлено много skills.

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

Есть два способа протестировать:

Дайте Claude вызвать skill автоматически - сформулируйте запрос, соответствующий описанию:

CODE
Can you help me review this code for security issues?

Или вызовите его напрямую, указав имя skill:

CODE
/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 напрямую, а затем выполните /reload-skills (v2.1.152+), чтобы повторно просканировать директории со skills. Перезапуск Claude Code тоже подойдёт, но не обязателен - skills из директорий, указанных в --add-dir, подхватываются на лету, а hook SessionStart, возвращающий reloadSkills: true, запускает такое же повторное сканирование.

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:

CODE
# Add to deny rules:
Skill

Разрешить или запретить определённые skills:

CODE
# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

Скрыть отдельные skill можно, добавив disable-model-invocation: true в их frontmatter.

Управление переопределением skill (skillOverrides)

Если skill проекта и skill пользователя имеют одинаковое имя, по умолчанию приоритет отдаётся проекту. Настройка skillOverrides (v2.1.129+) позволяет изменить это поведение. Добавьте её в ~/.claude/settings.json или в проектный .claude/settings.json:

json
{
  "skillOverrides": "name-only"
}

Допустимые значения:

ValueBehavior
"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 из непроверенных источников без аудита

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

Краткий справочник

IssueSolution
Claude doesn't use SkillMake description more specific with trigger terms
Skill file not foundVerify path: ~/.claude/skills/name/SKILL.md
YAML errorsCheck --- markers, indentation, no tabs
Skills conflictUse distinct trigger terms in descriptions
Scripts not runningCheck permissions: chmod +x scripts/*.py
Claude doesn't see all skillsToo many skills; check /context for warnings, then run /skill-doctor (v2.1.252+) to see which skills go unused and what they cost

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% окна контекста (значение по умолчанию: 8 000 символов). Каждая запись ограничена 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 и другие возможности

FeatureInvocationBest For
SkillsAuto or /nameReusable expertise, workflows
Slash CommandsUser-initiated /nameQuick shortcuts (merged into skills)
SubagentsAuto-delegatedIsolated task execution
Memory (CLAUDE.md)Always loadedPersistent project context
MCPReal-timeExternal data/service access
HooksEvent-drivenAutomated side effects

Встроенные skills

Claude Code поставляется со встроенным набором skills, которые всегда доступны без установки (наиболее полезные из них перечислены ниже; полный список см. в справочнике по commands):

SkillDescription
/batch <instruction>Orchestrate large-scale parallel changes across codebase using git worktrees
/claude-apiLoad Claude API/SDK reference; auto-activates on anthropic/@anthropic-ai/sdk imports
/datavizChart 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-promptsScan 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.
/simplifyCleanup-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 - коллекция skills, которые я использую ежедневно практически во всех своих проектах. Среди самых примечательных - logo-designer (на лету генерирует логотипы проектов) и ollama-optimizer (подстраивает производительность локальной LLM под ваше железо). Отличная отправная точка, если нужны готовые к использованию skills.

luongnv89/asm - Agent Skill Manager. Берёт на себя разработку skills, поиск дубликатов и тестирование. Команда asm link позволяет протестировать skill в любом проекте без копирования файлов - незаменимая вещь, когда skills у вас накопилось больше пары штук.

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


Последнее обновление: 6 сентября 2026 г. Версия Claude Code: 2.1.263 Источники:

ЛОКАЛЬНАЯ ОТМЕТКА · БЕЗ ПРОВЕРКИ
←ПРЕДЫДУЩИЙMemory Guide
СЛЕДУЮЩИЙSubagents - Complete Reference Guide→