Разработка пользовательских навыков

Чему вы научитесь

Закончив этот урок, вы сможете:

✅ Создавать структуру каталогов навыков, соответствующую спецификации
✅ Писать полные файлы определения SKILL.md (включая Front Matter, How It Works, Usage и другие главы)
✅ Писать Bash-скрипты, соответствующие спецификации (обработка ошибок, формат вывода, механизм очистки)
✅ Упаковывать навыки в Zip-файлы и публиковать их
✅ Оптимизировать эффективность контекста, позволяя Claude более точно активировать навыки

Текущие проблемы

Вы могли столкнуться с этими сценариями:

✗ Часто повторяете сложную операцию (например, развертывание на конкретную платформу, анализ форматов журналов), каждый раз объясняя Claude
✗ Claude не знает, когда активировать конкретную функцию, заставляя вас повторно вводить одни и те же команды
✗ Хотите инкапсулировать лучшие практики команды в переиспользуемые инструменты, но не знаете, с чего начать
✗ Написанные файлы навыков часто игнорируются Claude, не зная, в чем проблема

Когда использовать этот метод

Когда вам нужно:

📦 Инкапсулировать повторяющиеся операции: упаковывать часто используемые последовательности команд в одно нажатие
🎯 Точная активация: позволить Claude самостоятельно активировать навыки в конкретных сценариях
🏢 Стандартизировать процессы: автоматизировать стандарты команды (например, проверку кода, процесс развертывания)
🚀 Расширить возможности: добавить функции, которые Claude изначально не поддерживает

🎒 Подготовка перед началом

Перед началом убедитесь:

Предварительная проверка

Завершено Введение в Agent Skills
Установлен Agent Skills и вы знакомы с базовым использованием
Знакомы с базовыми операциями командной строки (Bash-скрипты)
Есть репозиторий GitHub (для публикации навыка)

Основная идея

Как работает Agent Skills:

Claude при запуске загружает только название и описание навыка, при обнаружении соответствующих ключевых слов считывает полное содержимое SKILL.md. Этот механизм lazy loading минимизирует потребление токенов.

Три основных элемента разработки навыков:

Структура каталогов: папка layout, соответствующая соглашениям об именах
SKILL.md: файл определения навыка, сообщает Claude, когда активировать и как использовать
Скрипты: фактический Bash-код выполнения, отвечающий за конкретные операции

[Изображение: схема активации навыка]

Следуйте за мной: создайте первый навык

Шаг 1: Создайте структуру каталогов

Почему Правильная структура каталогов — предпосылка для того, чтобы Claude мог распознать навык.

Создайте новый навык в каталоге skills/:

bash

cd skills
mkdir my-custom-skill
cd my-custom-skill
mkdir scripts

Структура каталогов должна быть:

skills/
  my-custom-skill/
    SKILL.md           # файл определения навыка (обязательно)
    scripts/
      deploy.sh        # выполняемый скрипт (обязательно)

Примечание: после завершения разработки весь каталог навыка нужно упаковать в my-custom-skill.zip для публикации (подробнее см. раздел "Упаковка навыков" ниже)

Вы должны увидеть:

my-custom-skill/ использует именование kebab-case (строчные буквы и дефисы)
Имя файла SKILL.md полностью заглавными буквами, должно точно совпадать
Каталог scripts/ хранит выполняемые скрипты

Шаг 2: Напишите SKILL.md

ПочемуSKILL.md — это ядро навыка, определяющее условия активации, способ использования и формат вывода.

Создайте файл SKILL.md:

markdown

---
name: my-custom-skill
description: Deploy my app to custom platform. Use when user says "deploy", "production", or "custom deploy".
---

# Custom Deployment Skill

Deploy your application to a custom platform with zero-config setup.

## How It Works

1. Detect framework from `package.json` (Next.js, Vue, Svelte, etc.)
2. Create a tarball of project (excluding `node_modules` and `.git`)
3. Upload to deployment API
4. Return preview URL and deployment ID

## Usage

```bash
bash /mnt/skills/user/my-custom-skill/scripts/deploy.sh [path]

Arguments:

path - Directory path or .tgz file to deploy (defaults to current directory)

Examples:

Deploy current directory:

bash

bash /mnt/skills/user/my-custom-skill/scripts/deploy.sh .

Deploy specific directory:

bash

bash /mnt/skills/user/my-custom-skill/scripts/deploy.sh ./my-app

Output

You'll see:

✓ Deployed to https://my-app-abc123.custom-platform.io
✓ Deployment ID: deploy_12345
✓ Claim URL: https://custom-platform.io/claim?code=...

JSON format (for machine-readable output):

json

{
  "previewUrl": "https://my-app-abc123.custom-platform.io",
  "deploymentId": "deploy_12345",
  "claimUrl": "https://custom-platform.io/claim?code=..."
}

Present Results to User

When presenting results to user, use this format:

🎉 Deployment successful!

**Preview URL**: https://my-app-abc123.custom-platform.io

To transfer ownership:
1. Visit claim URL
2. Sign in to your account
3. Confirm transfer

**Deployment ID**: deploy_12345

Troubleshooting

Network Error

Check your internet connection
Verify deployment API is accessible

Permission Error

Ensure directory is readable
Check file permissions on script

Framework Not Detected

Ensure package.json exists in project root
Verify framework is supported


**Вы должны увидеть**:
- Front Matter включает поля `name` и `description`
- `description` включает триггерные ключевые слова (например, "deploy", "production")
- Включает главы `How It Works`, `Usage`, `Output`, `Present Results to User`, `Troubleshooting`

### Шаг 3: Напишите Bash-скрипт

**Почему**
Скрипт — это часть, которая фактически выполняет операции, должна соответствовать спецификации ввода-вывода Claude.

Создайте `scripts/deploy.sh`:

```bash
#!/bin/bash
set -e  # выход при ошибке

# конфигурация
DEPLOY_API="${DEPLOY_API:-https://deploy.example.com/api}"

# разбор параметров
INPUT_PATH="${1:-.}"

# функция очистки
cleanup() {
  if [ -n "$TEMP_TARBALL" ] && [ -f "$TEMP_TARBALL" ]; then
    rm -f "$TEMP_TARBALL" >&2 || true
  fi
}
trap cleanup EXIT

# обнаружение фреймворка
detect_framework() {
  local path="$1"
  local framework=""

  if [ -f "${path}/package.json" ]; then
    if grep -q '"next"' "${path}/package.json"; then
      framework="nextjs"
    elif grep -q '"vue"' "${path}/package.json"; then
      framework="vue"
    elif grep -q '"@sveltejs/kit"' "${path}/package.json"; then
      framework="sveltekit"
    fi
  fi

  echo "$framework"
}

# основной процесс
FRAMEWORK=$(detect_framework "$INPUT_PATH")
echo "Detected framework: ${FRAMEWORK:-unknown}" >&2

# создание tarball
TEMP_TARBALL=$(mktemp -t deploy-XXXXXX.tgz)
echo "Creating tarball..." >&2
tar -czf "$TEMP_TARBALL" \
  --exclude='node_modules' \
  --exclude='.git' \
  -C "$INPUT_PATH" . >&2 || true

# загрузка
echo "Uploading..." >&2
RESULT=$(curl -s -X POST "$DEPLOY_API" \
  -F "file=@$TEMP_TARBALL" \
  -F "framework=$FRAMEWORK")

# проверка ошибок
if echo "$RESULT" | grep -q '"error"'; then
  ERROR_MSG=$(echo "$RESULT" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
  echo "Deployment failed: $ERROR_MSG" >&2
  exit 1
fi

# вывод результатов
echo "$RESULT"
echo "Deployment completed successfully" >&2

Вы должны увидеть:

Скрипт использует shebang #!/bin/bash
Использует set -e для обработки ошибок
Статусные сообщения выводятся в stderr (>&2)
Машинно-читаемый вывод (JSON) выводится в stdout
Включает cleanup trap

Шаг 4: Установите права выполнения

bash

chmod +x scripts/deploy.sh

Вы должны увидеть:

Скрипт стал выполняемым (ls -l scripts/deploy.sh показывает -rwxr-xr-x)

Шаг 5: Протестируйте навык

Протестируйте навык в Claude Code:

bash

# активация навыка
"Activate my-custom-skill"

# запуск развертывания
"Deploy my current directory using my-custom-skill"

Вы должны увидеть:

Claude активировал навык
Выполнил скрипт deploy.sh
Вывел результаты развертывания (включая previewUrl и deploymentId)

Контрольная точка ✅

Теперь проверьте, соответствует ли ваш навык спецификации:

[ ] Имя каталога использует kebab-case (например, my-custom-skill)
[ ] Имя файла SKILL.md полностью заглавными буквами, без ошибок
[ ] Front Matter включает поля name и description
[ ] description включает триггерные ключевые слова
[ ] Скрипт использует shebang #!/bin/bash
[ ] Скрипт использует set -e для обработки ошибок
[ ] Статусные сообщения выводятся в stderr (>&2)
[ ] JSON выводится в stdout
[ ] Скрипт включает cleanup trap

На что обратить внимание

Проблема 1: Навык не активируется

Симптом: вы говорите "Deploy my app", но Claude не активирует навык.

Причина: в description нет триггерных ключевых слов.

Решение:

markdown

# ❌ Ошибка
description: A tool for deploying applications

# ✅ Правильно
description: Deploy my app to production. Use when user says "deploy", "production", or "push to live".

Проблема 2: Смешанный вывод скрипта

Симптом: Claude не может разобрать вывод JSON.

Причина: статусные сообщения и вывод JSON смешаны.

Решение:

bash

# ❌ Ошибка: все выводится в stdout
echo "Creating tarball..."
echo '{"previewUrl": "..."}'

# ✅ Правильно: статусные сообщения в stderr
echo "Creating tarball..." >&2
echo '{"previewUrl": "..."}'

Проблема 3: Временные файлы не очищаются

Симптом: дисковое пространство постепенно заполняется.

Причина: скрипт не очищает временные файлы при выходе.

Решение:

bash

# ✅ Правильно: использовать cleanup trap
cleanup() {
  rm -f "$TEMP_TARBALL" >&2 || true
}
trap cleanup EXIT

Проблема 4: SKILL.md слишком длинный

Симптом: навык занимает слишком много контекста, влияет на производительность.

Причина: SKILL.md превышает 500 строк.

Решение:

Разместите подробную справочную документацию в отдельном файле
Используйте прогрессивное раскрытие (Progressive Disclosure)
Приоритетно используйте скрипты, а не встроенный код

Итоги урока

Ключевые моменты:

Структура каталогов: используйте kebab-case, включайте SKILL.md и каталог scripts/
Формат SKILL.md: Front Matter + How It Works + Usage + Output + Present Results to User + Troubleshooting
Спецификация скриптов: #!/bin/bash, set -e, вывод статуса в stderr, вывод JSON в stdout, cleanup trap
Эффективность контекста: держите SKILL.md < 500 строк, используйте прогрессивное раскрытие, приоритет скриптам
Упаковка и публикация: используйте команду zip -r для упаковки в {skill-name}.zip

Лучшая практика:

Описание конкретно, триггер понятен Статус в stderr, JSON в stdout Не забудьте trap, временные файлы очищайте Файлы не слишком длинные, скрипты занимают место

Следующий урок

В следующем уроке мы изучим Написание правил лучших практик React.
Вы узнаете:
Как написать файл правил, соответствующий спецификации
Использование шаблона _template.md для генерации правил
Определение уровня impact и тегов
Написание примеров кода Incorrect/Correct
Добавление ссылок и проверка правил

Приложение: Справочник по исходному коду

Нажмите, чтобы раскрыть расположение исходного кода

Обновлено: 2026-01-25

Функция	Путь к файлу	Строки
Спецификация разработки навыков	`AGENTS.md:9-69`	9-69
Определение структуры каталогов	`AGENTS.md:11-20`	11-20
Соглашение об именах	`AGENTS.md:22-27`	22-27
Формат SKILL.md	`AGENTS.md:29-68`	29-68
Лучшая практика эффективности контекста	`AGENTS.md:70-78`	70-78
Требования к скриптам	`AGENTS.md:80-87`	80-87
---	---	---
Метод установки пользователя	`AGENTS.md:98-110`	98-110

Ключевые константы:

Имя файла SKILL.md: должно быть полностью заглавными буквами, точное совпадение
/mnt/skills/user/{skill-name}/scripts/{script}.sh: формат пути скрипта

Ключевые функции:

Функция очистки скрипта cleanup(): для удаления временных файлов
Функция обнаружения фреймворка detect_framework(): выводит тип фреймворка из package.json

Разработка пользовательских навыков ​

Чему вы научитесь ​

Текущие проблемы ​

Когда использовать этот метод ​

🎒 Подготовка перед началом ​

Основная идея ​

Следуйте за мной: создайте первый навык ​

Шаг 1: Создайте структуру каталогов ​

Шаг 2: Напишите SKILL.md ​

Output ​

Present Results to User ​

Troubleshooting ​

Шаг 4: Установите права выполнения ​

Шаг 5: Протестируйте навык ​

Контрольная точка ✅ ​

На что обратить внимание ​

Проблема 1: Навык не активируется ​

Проблема 2: Смешанный вывод скрипта ​

Проблема 3: Временные файлы не очищаются ​

Проблема 4: SKILL.md слишком длинный ​

Итоги урока ​

Следующий урок ​

Приложение: Справочник по исходному коду ​

Разработка пользовательских навыков

Чему вы научитесь

Текущие проблемы

Когда использовать этот метод

🎒 Подготовка перед началом

Основная идея

Следуйте за мной: создайте первый навык

Шаг 1: Создайте структуру каталогов

Шаг 2: Напишите SKILL.md

Output

Present Results to User

Troubleshooting

Шаг 4: Установите права выполнения

Шаг 5: Протестируйте навык

Контрольная точка ✅

На что обратить внимание

Проблема 1: Навык не активируется

Проблема 2: Смешанный вывод скрипта

Проблема 3: Временные файлы не очищаются

Проблема 4: SKILL.md слишком длинный

Итоги урока

Следующий урок

Приложение: Справочник по исходному коду