Лучшие практики использования
Чему вы научитесь
Закончив этот урок, вы сможете:
- ✅ Точно выбирать ключевые слова запуска, чтобы AI активировал навык в нужное время
- ✅ Оптимизировать управление контекстом, минимизировать потребление токенов, повышать скорость ответов
- ✅ Обрабатывать сценарии сотрудничества с несколькими навыками, избегая конфликтов и путаницы
- ✅ Освоить распространенные паттерны использования, повышая эффективность работы
Текущие проблемы
Вы могли столкнуться с этими сценариями:
- ✗ Ввели "помоги развернуть", но AI не активировал навык Vercel Deploy
- ✗ Одна задача запустила несколько навыков, AI не знал, какой использовать
- ✗ Навыки заняли много контекста, из-за чего AI "забыл" ваши требования
- ✗ Каждый раз приходилось переобъяснять задачу, не зная, как позволить AI запомнить ваши привычки
Когда использовать этот метод
Когда вы используете Agent Skills и сталкиваетесь с:
- 🎯 Неточный запуск: навык не активируется или активируется неправильно
- 💾 Давление на контекст: навыки занимают слишком много токенов, влияют на другие диалоги
- 🔄 Конфликты навыков: несколько навыков активируются одновременно, AI выполняет беспорядочно
- ⚡ Снижение производительности: ответы AI становятся медленными, нужно оптимизировать способ использования
Основная идея
Философия дизайна Agent Skills:
Agent Skills использует механизм lazy loading — Claude при запуске загружает только имя и описание навыка (около 1-2 строк), при обнаружении соответствующих ключевых слов считывает полное содержимое SKILL.md. Это разработка позволяет минимизировать потребление контекста, сохраняя точность запуска навыков.
Три ключевых измерения эффективности использования:
- Точность запуска: выберите подходящие ключевые слова запуска, чтобы навыки активировались в нужное время
- Эффективность контекста: управляйте длиной содержимого навыков, избегайте чрезмерного использования токенов
- Ясность сотрудничества: четко определите границы навыков, избегайте конфликтов нескольких навыков
Лучшие практики 1: точный выбор ключевых слов запуска
Что такое ключевые слова запуска?
Ключевые слова запуска — это ключевые слова, определенные в поле description в SKILL.md, которые сообщают AI, когда нужно активировать этот навык.
Ключевой принцип: описание должно быть конкретным, ключевые слова — явными
Как писать эффективное описание?
❌ Неправильный пример: описание слишком размыто
yaml
---
name: my-deploy-tool
description: A deployment tool for applications # слишком размыто, не может активировать
---Проблемы:
- Нет четкого сценария использования
- Отсутствуют ключевые слова, которые может использовать пользователь
- AI не может определить, когда активировать
✅ Правильный пример: описание конкретное и содержит ключевые слова
yaml
---
name: vercel-deploy
description: Deploy applications and websites to Vercel. Use this skill when user requests deployment actions such as "Deploy my app", "Deploy this to production", "Create a preview deployment", "Deploy and give me link", or "Push this live". No authentication required.
---Преимущества:
- Четкий сценарий использования (Deploy applications)
- Указаны конкретные фразы запуска ("Deploy my app", "Deploy this to production")
- Описана уникальная ценность (No authentication required)
Руководство по выбору ключевых слов запуска
| Сценарий написания | Рекомендуемые ключевые слова | Избегайте использования |
|---|---|---|
| Развертывание | "deploy", "production", "push", "publish" | "send", "move" |
| Анализ кода | "review", "check", "audit", "optimize" | "look at", "see" |
| Проверка дизайна | "accessibility", "a11y", "UX check", "design audit" | "design", "style" |
| Оптимизация производительности | "optimize", "performance", "improve speed", "faster", "better" |
⚠️ Предупреждение о распространенных ошибках
Избегайте эти ошибки
❌ Только общие слова
yaml
description: A tool for code review # "code review" слишком общее✅ Конкретный сценарий + ключевые слова
yaml
description: Review React components for performance issues. Use when user says "review performance", "check optimization", or "find bottlenecks".❌ Недостаточно ключевых слов
yaml
description: Deploy to Vercel # только один сценарий✅ Покрытие нескольких выражений
yaml
description: Deploy to Vercel. Use when user says "deploy", "push live", "create preview", or "publish".Лучшие практики 2: приемы управления контекстом
Почему управление контекстом важно?
Токены — это ограниченный ресурс. Если файл SKILL.md слишком длинный, он займет много контекста, из-за чего AI "забудет" ваши требования или ответы станут медленными.
Ключевой принцип: держите SKILL.md коротким
Золотое правило
Держите файл SKILL.md в 500 строках
Согласно официальной документации, следующие стратегии могут минимизировать использование контекста:
| Стратегия | Описание | Эффект |
|---|---|---|
| Держите SKILL.md лаконичным | Поместите подробные справочные материалы в отдельные файлы | Минимизация начальной загрузки |
| Пишите конкретные описания | Помогайте AI точно определить, когда активировать | Избегайте ложных срабатываний |
| Используйте прогрессивное раскрытие | Читайте подробную поддержку только когда нужно | Контролируйте фактическое потребление токенов |
| Приоритет скриптам | Скрипт не потребляет контекст при выводе | Значительное уменьшение использования токенов |
Как применять прогрессивное раскрытие?
Сценарий: вашему навыку нужна документация API, примеры конфигурации и т.д.
❌ Неправильный подход: всё в SKILL.md
markdown
---
name: my-api-skill
description: Integrate with My API. Use when user says "call API", "send request", or "fetch data".
---
# API Skill
## API Reference
(здесь 2000 строк документации API)
## Configuration Examples
(здесь 500 строк примеров)
## Usage Guide
(здесь 2000 строк инструкций)Проблемы:
- Файл превышает 500 строк
- Каждая активация загружает весь контент
- Большая часть может не использоваться
✅ Правильный подход: раздельные файлы
markdown
---
name: my-api-skill
description: Integrate with My API. Use when user says "call API", "send request", or "fetch data".
---
# API Skill
Quick start guide for My API integration.
## Quick Setup
1. Get API key from https://api.example.com/keys
2. Add to environment: `export MY_API_KEY="your-key"`
3. Run: `bash scripts/api-client.sh`
## Common Operations
### Fetch user data
```bash
bash scripts/api-client.sh get /users/123Create new resource
bash
bash scripts/api-client.sh post /users '{"name":"John"}'Reference Documentation
For complete API reference, see:
**Преимущества**:
- `SKILL.md` — только около 30 строк
- AI считывает подробную документацию только когда нужно
- Значительная часть потребления токенов — при выводе скрипта, а не при чтении документа
### Сравнение: Vercel Deploy vs React Best Practices
| Навык | Строки SKILL.md | Стратегия оптимизации | Рекомендуемые сценарии |
|--- | --- | --- | ---|
| Vercel Deploy | ~60 строк | Ясные инструкции + скриптовая обработка сложной логики | Развертывание приложений |
| React Best Practices | ~300 строк | Индекс правил + подробные правила в AGENTS.md | Анализ производительности React |
| Web Design Guidelines | ~50 строк | Конвейерный дизайн + динамическое извлечение из GitHub | Аудит интерфейса UX |
**Принцип**:
> Не пишите всё содержимое в `SKILL.md`, позвольте ему стать "путеводителем", а не "полным руководством".
---
## Лучшие практики 3: сценарии сотрудничества с несколькими навыками
### Сценарий 1: Навык A и Навык B имеют перекрывающиеся условия запуска
**Проблема**: вы говорите "review my code", одновременно запускаются React Best Practices и Web Design Guidelines.
#### ✅ Решение: четкое различение триггерных слов
```yaml
# React Best Practices
name: react-performance
description: Review React components for performance issues. Use when user says "review performance", "optimize React", "check bottlenecks".
# Web Design Guidelines
name: web-design-audit
description: Audit UI for accessibility and UX issues. Use when user says "check accessibility", "review UX", "audit interface".Результат:
- "review performance" → только навык React
- "check accessibility" → только навык Web Design
- "review my code" → ни один не активируется, AI решает самостоятельно
Сценарий 2: нужно использовать несколько навыков одновременно
Лучшие практики: явно сообщите AI, какие навыки нужны
Рекомендуемый способ общения:
Мне нужно выполнить две задачи:
1. Развернуть приложение (использовать vercel-deploy)
2. Проверить производительность компонентов (использовать react-best-practices)Причины:
- Четкие границы навыков, избегайте путаницы
- Позволяет AI выполнять задачи по порядку
- Избегает конкуренцию за контекст
Сценарий 3: цепочка вызов навыков (вывод одного — вход другого)
Пример: оптимизация перед развертыванием
bash
# Шаг 1: использование React Best Practices для оптимизации
"Review src/components/Header.tsx for performance issues using react-best-practices skill"
(модификация)
# Шаг 2: использование Vercel Deploy для развертывания
"Deploy optimized code to Vercel"Лучшие практики:
- Четкие инструкции по порядку
- Подтверждение завершения каждого шага
- Избегайте параллельной обработки зависимых задач
Лучшие практики 4: рекомендации по оптимизации производительности
1. Упрощение контекста диалога
Проблема: после длительного диалога контекст становится длинным, ответы замедляются.
✅ Решение: запуск нового диалога или использование "Clear Context"
bash
# Claude Code
/clear # очистить контекст, сохранить навыкиПримечание: /clear сохраняет установленные навыки, но очищает диалоговое содержимое, позволяя начать с чистого листа.
2. Избегайте повторной загрузки навыков
Проблема: одна и та же задача несколько раз запускает навыки, расходуя токены впустую.
❌ Неправильный подход
Пользователь: Deploy my app
AI: (загружает vercel-deploy, выполняет)
Пользователь: Deploy to production
AI: (снова загружает vercel-deploy, выполняет)✅ Правильный подход
Пользователь: Deploy to production
AI: (загружает vercel-deploy, выполняет один раз)Ключевой момент: используйте однозначные инструкции, AI запомнит результат.
3. Используйте скрипты вместо встроенного кода
Сравнение: выполнение той же задачи, какой подход менее потребляет?
| Подход | Потребление токенов | Рекомендуемые сценарии |
|---|---|---|
| Встроенный код (в SKILL.md) | Высокое (загружается при каждом запуске) | Простые задачи (<10 строк) |
| Bash-скрипты | Низкое (загружается только путь к скрипту) | Сложные задачи (>10 строк) |
Пример:
markdown
## ❌ Встроенный код (не рекомендуется)
```bash
tar -czf package.tar.gz \
--exclude='node_modules' \
--exclude='.git' \
&& curl -X POST $API_URL \
-F "file=@package.tar.gz"✅ Скрипты (рекомендуется)
bash
bash scripts/deploy.sh(скрипт загружается только при первом запуске, вывод результата не потребляет контекст)
### 4. Мониторинг использования токенов
**Клиент Claude Code**:
```bash
# Проверка текущего использования токенов
/tokenПолезные показатели:
- Общее количество токенов в диалоге
- Нагрузка навыков (какие навыки загружены)
- Длина контекста
Распространенные паттерны использования и примеры
Паттерн 1: рабочий процесс быстрой итерации
bash
# 1. Написание кода
vim src/App.tsx
# 2. Немедленная проверка производительности
"Review this for performance issues using react-best-practices skill"
(модификация)
# 3. Повторная проверка
"Review again"
(дополнительные улучшения)
# 4. Развертывание
"Deploy to production"Ключевые моменты:
- Используйте короткие инструкции (AI уже знает контекст)
- Повторяйте инструкции для быстрой активации
- Четкая последовательность задач
Паттерн 2: проверка нового проекта
bash
# Создание проекта Next.js
npx create-next-app@latest my-app
# Установка Agent Skills
npx add-skill vercel-labs/agent-skills
# Начальный аудит всех UI файлов
"Check accessibility for all UI files"
"Review performance for all components"
# Развертывание тестовое
"Deploy to production"Проверочный список для команды:
- [ ] Создан проект
- [ ] Установлены навыки
- [ ] Выполнен аудит доступности
- [ ] Выполнена проверка производительности
- [ ] Развернуто тестовое окружение
Паттерн 3: шаблон совместной работы команды
bash
# Cloning team project
git clone team-project
cd team-project
# 1. "Review performance for all new changes"
"Review performance for all new changes using react-best-practices skill"
(modification)
# 2. "Check accessibility of modified files"
"Check accessibility of modified files using web-design-guidelines skill"
(modification)
# 3. "Deploy to staging"
"Deploy to staging environment"Стандарты команды:
- Определение единых ключевых слов для совместной работы
- Стандартизированная последовательность задач
- Четкое разделение ответственности
Предупреждения о распространенных ошибках
Ошибка 1: навык активировался, но не принес результата
Симптомы: вы говорите "Deploy my app", AI заявляет "буду использовать vercel-deploy навык", но ничего не происходит.
Возможные причины:
- Ошибка пути к скрипту
- Отсутствие прав выполнения скрипта
- Файл не в правильном расположении
Решение:
bash
# Проверка каталога навыков
ls -la ~/.claude/skills/vercel-deploy/
# Проверка прав скрипта
chmod +x ~/.claude/skills/vercel-deploy/scripts/deploy.sh
# Ручное тестирование скрипта
bash ~/.claude/skills/vercel-deploy/scripts/deploy.sh .Ошибка 2: активирован неправильный навык
Симптомы: вы говорите "check code", активируется Web Design Guidelines вместо React Best Practices.
Причина: конфликты ключевых слов в описаниях навыков.
Решение: измените триггерные слова, сделайте их более конкретными:
yaml
# ❌ Раньше
description: "Check code for issues"
# ✅ После изменения
description: "Review React code for accessibility and UX"Ошибка 3: AI "забыл" навык в следующем цикле
Симптомы: первый диалог можно использовать навык, во втором навык уже не активируется.
Причина: контекст слишком длинный, информация о навыках вытеснена.
Решение:
bash
/clear # очистить контекстИтоги урока
Ключевые моменты:
- Ключевые слова запуска: описание должно быть конкретным, включать возможные фразы пользователя
- Управление контекстом: держите SKILL.md < 500 строк, используйте прогрессивное раскрытие, приоритет скриптам
- Сотрудничество навыков: четко определите границы навыков, последовательное выполнение задач, избегайте конфликтов
- Оптимизация производительности: упрощайте контекст диалога, избегайте повторной загрузки, следите за использованием токенов
Мнемоника лучших практик:
Описание конкретное, запуск явный Файл не слишком длинный, скрипт занимает место Множество навыков: границы четкие, задачи по порядку Контекст должен быть простым, регулярно очищайтесь от застоя
Следующий урок
В следующем уроке мы глубоко изучим Техническая архитектура и детали реализации Agent Skills.
Вы узнаете:
- Подробности процесса сборки (parse → validate → group → sort → generate)
- Как работает парсер правил
- Типовая система и поток данных
- Алгоритм обнаружения фреймворков скрипта развертывания
Приложение: справочник по исходному коду
Нажмите, чтобы раскрыть расположение исходного кода
Обновлено: 2026-01-25
| Функция | Путь к файлу | Строки |
|---|---|---|
| Лучшие практики управления контекстом | AGENTS.md:70-78 | 70-78 |
| Примеры эффективного запуска | README.md:88-102 | 88-102 |
| Ключевые слова запуска React | SKILL.md | 1-30 |
| Ключевые слова запуска Vercel | SKILL.md | 1-30 |
Ключевые принципы:
- Keep SKILL.md under 500 lines: держите файл навыков кратким
- Write specific descriptions: пишите конкретные описания для точного запуска
- Use progressive disclosure: используйте прогрессивное раскрытие для подробностей
- Prefer scripts over inline code: приоритет скриптам вместо встроенного кода