Skip to content

guide.md

Latest commit

 

History

History
110 lines (75 loc) · 6.49 KB

guide.md

File metadata and controls

110 lines (75 loc) · 6.49 KB
Raw

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

Это краткое руководство объясняет, что такое Agent Skills, как их устанавливать, создавать и безопасно использовать.

Вернуться к каталогу skills.

Что такое Agent Skills

Agent Skill — это папка с инструкциями, скриптами и вспомогательными материалами, которая обучает AI-агента выполнять конкретную задачу или рабочий процесс.

Обычно агент сначала видит только имя и краткое описание skill. Полные инструкции загружаются, когда задача подходит под его назначение. Такой подход называют progressive disclosure: контекст не переполняется всеми инструкциями сразу.

Skills подходят для:

  • code review, отладки, тестирования и работы с Git;
  • архитектурных и командных процессов;
  • frontend, backend, DevOps, cloud и data-задач;
  • подготовки документов, исследований и контента;
  • хранения внутренних правил и знаний проекта.

Skill и MCP — не одно и то же

  • Skill объясняет агенту, как выполнять задачу: шаги, ограничения, примеры и проверки.
  • MCP предоставляет агенту инструменты и данные во время выполнения: API, файловые системы, базы данных и внешние сервисы.

Они дополняют друг друга: MCP дает возможности, а skill задает надежный способ их использовать.

Как установить skill

Многие современные репозитории поддерживают универсальный CLI skills:

# Посмотреть доступные skills
npx skills add owner/repository --list

# Установить выбранный skill в текущий проект
npx skills add owner/repository --skill skill-name

# Установить глобально для всех проектов
npx skills add owner/repository --skill skill-name -g

Пример:

npx skills add vercel-labs/agent-skills --list
npx skills add vercel-labs/agent-skills --skill web-design-guidelines
Режим Когда использовать
Project-local Skill должен храниться вместе с репозиторием и быть одинаковым у всей команды.
Global Skill нужен лично вам во многих несвязанных проектах.

Не все проекты используют одинаковый способ установки. Перед установкой проверяйте README конкретного репозитория: некоторые skills распространяются через Claude Code Marketplace, встроенный установщик Codex, собственный CLI или ручное копирование папки.

Как устроен skill

Минимальный skill содержит только SKILL.md. Более сложный может включать скрипты, справочные материалы и шаблоны:

my-skill/
├── SKILL.md
├── scripts/       # Необязательные исполняемые скрипты
├── references/    # Документация и дополнительные инструкции
└── assets/        # Шаблоны и статические ресурсы

Минимальный SKILL.md:

---
name: angular-code-review
description: Reviews Angular code for correctness, architecture, accessibility, performance, and maintainability. Use for pull requests and code review tasks.
---

# Angular Code Review

1. Read the changed files and project conventions.
2. Find correctness and regression risks first.
3. Check Angular-specific architecture and performance.
4. Report actionable findings with file references.
5. Run or suggest the smallest relevant validation.

Как создать свой skill

  1. Выберите одну понятную задачу или workflow.
  2. Создайте папку с SKILL.md и YAML frontmatter name + description.
  3. В description явно укажите, что делает skill и когда его активировать.
  4. Запишите конкретный процесс, проверки, ограничения и ожидаемый результат.
  5. Проверьте skill на реальных запросах, включая случаи, когда он не должен активироваться.

Хороший skill не просто хранит большой prompt. Он описывает повторяемый процесс, снижает количество неоднозначных решений и дает агенту способ проверить результат.

Безопасность

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

Перед установкой стороннего skill:

  • прочитайте SKILL.md, install-скрипты и содержимое scripts/;
  • проверьте, какие файлы, команды, токены и внешние сервисы он использует;
  • не передавайте секреты skill, которому они не нужны;
  • для команды и CI фиксируйте проверенную версию, tag или commit;
  • запускайте неизвестную автоматизацию в изолированной среде.

Как добавить проект в каталог

Требования, формат записи и checklist находятся в CONTRIBUTING.md.