Содержание

01 · Что такое Agent Skill (и чем не является)

Agent Skill — discoverable bundle: YAML frontmatter (закрывается ---) + Markdown-тело + опциональные исполняемые артефакты. Runtime (Cursor 2.4+) на этапе инициализации сессии индексирует только Level-1 metadata; полный SKILL.md попадает в контекст после semantic match по description, а не по имени файла в репозитории.

Skill ≠ замена reasoning модели. Skill ≠ MCP-server. Skill ≠ OpenClaw plugin manifest — последний описывает каналы gateway; процедурный текст из ClawHub-паков можно портировать в SKILL.md, но discovery path остаётся product-specific.

Типовые кейсы: (1) solo — conventional commits skill в ~/.cursor/skills/; (2) platform — .cursor/skills/security-review/ в monorepo; (3) contractor — личные skills не коммитятся в клиентский git. Общий контракт — agentskills.io/specification.

02 · Agent Skills vs Cursor Rules

Rules (.cursor/rules/*.mdc, legacy .cursorrules) инжектятся при совпадении glob/ручного выбора — это policy layer. Skills — procedural layer с явным trigger в description.

Измерение	Cursor Rules	Agent Skills
Слой	Policy / style / deny-list	Runbook / SOP
Типичный объём L1	N файлов × сотни токенов	~100 токенов × число skills
Исполнение	текст → модель → edit	текст + `exec scripts/*.sh`
Версионирование	git в .cursor/rules	git + semver теги на skill
Портативность	Cursor paths	agentskills.io layout

Эвристика для platform-команд: «без force push на main» — Rule; «11 шагов staging deploy с scripts/preflight.sh exit 0» — Skill. Дублирование одного абзаца в Rule и Skill удваивает Level-2 load при ложном trigger.

03 · Спецификация agentskills.io (поля и ограничения)

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

name — regex [a-z0-9-]{1,64}, kebab-case, совпадает с именем каталога; не начинать/заканчивать на -
description — ≤1024 символов; обязательны WHAT + WHEN; включайте строки ошибок и CLI-фразы из продакшена

Опционально: license, compatibility (≤500 символов — OS, brew-пакеты, min Node), metadata (произвольный KV для CI), allowed-tools (experimental whitelist имён tools на invoke skill).

Рекомендуемые подкаталоги: scripts/ (исполняемые, shebang + set -euo pipefail для bash), references/ (длинные схемы API), assets/ (шаблоны отчётов). CI-check пример: test "$(basename "$PWD")" = "$(yq .name SKILL.md)".

04 · SKILL.md и пути discovery в Cursor

                        ---

name: deploy-staging

description: Deploy to staging via gh and kubectl. Use when user mentions staging deploy, hotfix staging, RC validation.

compatibility: kubectl context=staging; gh auth; macOS 15+ or Linux with BSD userland parity for scripts.

---

## Preconditions

- CI green on target SHA (check with scripts/ci-status.sh)

## Steps

1. scripts/preflight.sh --env staging  # expect exit 0

Personal: ~/.cursor/skills/<name>/SKILL.md — все репозитории на машине
Project: .cursor/skills/<name>/SKILL.md — в git для команды
Не использовать для team skills: ~/.cursor/skills-cursor/ (встроенные skills Cursor, в т.ч. authoring для /create-skill)

Description пишите от третьего лица («Processes Excel…») — строка попадает в system-facing selection context. Тело SKILL.md держите <500 строк; вложенные ссылки глубже одного hop могут подгружаться частично.

05 · Трёхуровневая загрузка (progressive disclosure)

Level 1 — Metadata: при session init runtime регистрирует name+description каждого skill (~100 токенов/шт.). Агент строит mental index без оплаты полного runbook.
Level 2 — Instructions: при match загружается весь Markdown-body (<5k токенов рекомендация spec). Здесь чеклисты, ветвления if/else, ссылки на references.
Level 3 — Resources: чтение/выполнение scripts/validate.py, 40-страничного style guide из references/ только когда workflow требует.

Флаг disable-model-invocation: true (часто в generated skills) отключает ambient auto-load — skill активируется явным именем или skill picker. Для PDF-heavy repo, где каждый upload требует одного skill, флаг снимают осознанно.

Инженерный аналог: Level 1 = оглавление runbook; Level 2 = открытая глава; Level 3 = приложения и shell hooks. Без этого агент либо игнорирует жирные Rules, либо съедает context до чтения вашего diff.

06 · Авторинг через /create-skill

Slash-команда /create-skill вызывает internal authoring skill: интервью purpose → triggers → storage → scripts. После генерации чеклист:

folder name === name в frontmatter
description содержит verbatim-триггеры из тикетов
каждый script документирован с expected exit codes (0 success, 2 config, 10 network)
references только на один уровень вложенности от SKILL.md
smoke: новый chat, минимальный user prompt, проверка auto-invoke (если нужен)

Hermes ~/.hermes/skills/ с closed-loop distillation — см. 30-дневный отчёт Hermes Skills; layout Cursor и paths discovery различаются.

07 · Production practices

Orthogonal skills

Один skill = один outcome. «iOS archive upload» и «Play upload» раздельно — иначе description размывается и Level 2 раздувается.

Freedom vs fragility

DB migration / cert rotation — low freedom (pinned script + exit code table). Code review culture — high freedom (prose).

Feedback loop в SKILL.md

Явно: «run validator → if non-zero fix → re-run until pass». Иначе агент трактует известный linter warning как success.

Security

Secrets только через env/SecretRef. Сторонние skill hubs — signed tags, internal mirror: изоляция ClawHub.

08 · FAQ: Skills vs MCP

Skill = MCP?

Нет. MCP — JSON-RPC transport к внешнему state (Jira issue status, tail logs). Skill — статические инструкции + локальный subprocess.

Когда MCP вместо Skill?

Fresh data each turn → MCP. Human release cadence procedure → Skill. Композиция: Skill описывает порядок вызовов MCP tools.

Git через MCP vs Skill?

Локальный git уже в tool surface агента; Skill кодирует ваши squash/rebase rules. MCP нужен при custom forge API или запрете shell git. См. MCP и approvals.

09 · Sandbox: пять шагов аренды Mac для script-skills

Skill с scripts/deploy.sh может: chmod prod paths, дернуть webhook, brew install пакеты в userland хоста Cursor. WSL не эмулирует codesign, notarytool, TCC-prompts — нужен bare-metal macOS.

Шаг 1 — Арендовать чистый узел

Apple Silicon, отдельный account, SSH (+ VNC для GUI-проверки TCC). Тарифы: руководство по ценам Mac mini M4, тарифы bare-metal macOS. Один узел — один эксперимент в сутки.

Шаг 2 — Синхронизировать только skills

rsync -av --exclude .env .cursor/skills/my-skill/ user@host:~/skill-sandbox/ → symlink в ожидаемые paths. Не клонировать весь ~.

Шаг 3 — Зависимости по compatibility

nvm install, python3 -m venv, brew bundle. chmod +x scripts/*. Ручной прогон --help каждого бинарника до agent turn.

Шаг 4 — Dry-run, затем agent

./scripts/deploy.sh --dry-run 2>&1 | tee /tmp/skill-dry.log; фиксируйте $?. Cursor на арендованном Mac (local UI или SSH remote): сравните command trace агента с baseline. Drift → ужесточить SKILL.md (low freedom).

Шаг 5 — Промотировать или wipe

Merge в main / personal path при pass. Иначе — возврат без следов (5 шагов). Операционка SSH/VNC: FAQ посуточной аренды.

Аренда vs покупка для skill R&D

CapEx Mac mini + pollution primary Keychain — плохой tradeoff для episodic validation. Посуточная аренда привязывает cost к 24–72h risk window. После стабилизации skill всё равно арендуйте на regression при смене macOS/Xcode — compatibility в frontmatter честно только после последнего прогона.

10 · Общий FAQ

Сколько skills включать?

Level 1 дешёв, но 40 размытых descriptions добавляют шум. 10–20 sharp skills/repo; archive 90d idle.

Порт на Claude Code?

agentskills.io layout — да; переписать product-specific hooks.

Skill не триггерится?

Verbatim triggers, split overloaded skills, проверить disable-model-invocation, invoke by name.

OpenClaw packs → SKILL.md?

Процедуры — да; gateway wiring — нет. ClawHub day-rental trial.

Rules держат guardrails. MCP — live data. Skills — SOP, которые переживают смену модели. Пишите под agentskills.io, уважайте три уровня загрузки, используйте /create-skill, арендуйте изолированный Mac, когда scripts/ могут навредить — так работают зрелые Cursor-команды в 2026.