Створення якісної навички агента Claude: уроки з проекту тренера з бігу
Створення надійної навички Claude Agent: детальні описи, оцінка перед написанням тексту, SKILL.md як маршрутизатор, скрипти замість тексту та обмеження щодо облікових даних у CI.
Джерела: I Missed My Running Goal Three Years Running. So I Built an Agent Skill.
Уявіть бігуна, який протягом трьох років поспіль ставив собі ціль пробігти 1 000 км, але щоразу її не досягав, завершивши ці три роки з загальною відстанню близько 2 500 км. Проблемою не була наполегливість. Траплялися травми, необхідність починати знову та напружені тижні. Бракувало плану, адже мотивація добре працює до того дня, поки раптово не припиняє це робити.
Одним із рішень є припинити покладатися на силу волі та створити систему. Саме так виник running-coach — навичка Claude Agent, яка планує індивідуальні пробіги та цілі тижні на основі власної історії людини, перетворює кожен тиждень на короткий електронний звіт у стилі редакційної статті та навіть підбирає список пісень відповідно до тривалості майбутнього пробігу.
Біг тут є лише фоном. Набагато кориснішою темою є те, що потрібно для розвитку хорошої навички — тобто такої, яка надійно функціонує, обмежено використовує контекст, поводиться однаково на кожній платформі та не занепадає з часом. Нижче кожна з опублікованих Anthropic практик створення контенту узгоджується з тим, як цей проект їх застосовує.
Що таке навичка агента
Навичка — це папка. У її корені знаходиться файл SKILL.md, який починається з YAML-фронтматеріалу, що містить name та description, а потім продовжується інструкціями у форматі Markdown. Поруч з ним можуть знаходитися документи для посилань, скрипти, шаблони та інші ресурси.
Цікавою є частина, пов’язана з тим, як завантажується навичка, за допомогою трьохрівневої моделі під назвою поступове розкриття:
- Рівень 1, метадані. Завантажується завжди під час запуску, приблизно на 100 токенів на кожну навичку. Він складається лише з назви та опису.
- Рівень 2, інструкції. Завантажується лише тоді, коли активується навичка, і обмежується приблизно 5 тис. токенів. Це основна частина файлу
SKILL.md. - Рівень 3, ресурси. Завантажуються за потреби за допомогою bash та залишаються доступними доти, доки до них не звернуться. Тут знаходяться файли-довідки, скрипти та ресурси.
Anthropic порівнює навичку з посібником з адаптації, написаним для нового колеги. Основний принцип усього іншого полягає у тому, що вікно контексту є спільним ресурсом, загальнодоступною річчю. Усе, що використовує навичка, недоступне для решти інформації, яку агент намагається зберегти в пам’яті.
1. Опис виконує функцію API
На рівні 1 усе, що модель бачить щодо певної навички, — це її опис. Він виконує скоріше функцію таблиці маршрутизації, ніж документації, адже модель порівнює надійшлий запит із нею, щоб вирішити, чи активувати цю навичку. У описі мають бути вказані як функції навички, так і момент її використання; він має бути написаний у третій особі та не перевищувати 1 024 символів, причому практичний ліміт становить близько 200 символів, якщо ви хочете, щоб він відображався повністю у вибірнику claude.ai. Ось опис, який використовує running-coach:
name: running-coach
description: >-
Plans a run or a whole week as Google Calendar blocks, builds a weekly
running digest email, and makes playlists — from Strava, Spotify, AccuWeather
and Calendar. Use for pacing or planning a week.
Подивіться, як це побудовано. Спочатку описується, що може робити ця функція (планувати пробіжку, створювати короткі огляди, формувати плейлисти), потім — коли її варто використовувати (для контролю темпу чи планування тижня), а також вказуються джерела даних, щоб запит у стилі Strava міг посилатися на цю функцію. Назва записується з великої літери в кожному слові та ідентична назві каталогу — це суворе правило, а не смакова примха, яке дотримується механізм компіляції проекту, як покаже подальший опис.
Неможливо заздалегідь визначити, чи буде опис ефективним. Його потрібно протестувати, тому першою річчю у репозиторії є набір оцінок, а не документація.
2. Спочатку напишіть оцінки, а вже потім відшліфуйте текст
Рада компанії Anthropic — спочатку створювати механізми оцінки, щоб вирішувати реальні проблеми, а не ті, які ви собі уявили. У проекті є чотири файли з сценаріями у папці evals/, по одному на кожну здатність. Це не тести на одиниці, а контракти поведінки, написані простою мовою. Ось файл для планування виконання:
{
"skills": ["running-coach"],
"query": "I'm heading out for 8k this evening, how long is that going to take me?",
"expected_behavior": [
"Triggers the running-coach skill without being named, and routes to the planning capability",
"Reads references/run-planning.md and does not read the digest or playlist references",
"Runs scripts/cache.py status before projecting…",
"Executes scripts/planning/plan_run.py 8 rather than reading its source or reimplementing Riegel inline",
"Reports the projected finish time, the pace, and the recommended effort band…",
"Never asks for or uses a Strava access token"
]
}
Кожне твердження кодує найкращу практику. Запуск тестів без вказання їхнього опису перевіряє якість опису. Читання лише відповідних базових тестів — це принцип поступового розкриття інформації. Запуск скрипта без його повторної реалізації перевіряє перевагу скриптів над прозою. Не торкатися жодного токена — це перевірка меж автентифікаційних даних. Разом вони перетворюють всю філософію проектування на спостережувану поведінку, а решта процесу створення спрямована на забезпечення їхнього успішного функціонування.
3. Використання SKILL.md як маршрутизатора
Найпоширеніший спосіб витратити всі ресурси контексту навички — це помістити все в SKILL.md. Кращим підходом є використання цього файлу як змісту, який посилається на більш детальні матеріали за потреби. Тримайте його коротким та робіть посилання на рівні одного рівня глибини, адже агенти зазвичай читають глибоко вкладені файли лише частково, в результаті чого отримують неповну картину.
Кожну з чотирьох можливостей тут знадобилася б ціла сторінка для пояснення, тому SKILL.md не пояснює жодної з них. Він спрямовує на:
| Capability | Reference | Entry point |
| -------------- | -------------------------------- | --------------------------------- |
| Plan a run | references/run-planning.md | scripts/planning/plan_run.py |
| Plan the week | references/week-planning.md | scripts/planning/plan_week.py |
| Weekly digest | references/weekly-digest.md | scripts/digest/run_pipeline.py |
| Run playlist | references/run-playlist.md | scripts/playlist/build_playlist.py|
Work out which one is wanted, then read only that capability's reference.
Запросіть плейліст, і агент відкриває лише run-playlist.md, нічого більше. Специфікація процесу обробки дайджесту, його підводні камені та примітки до шаблонів ніколи не потрапляють у контекст, оскільки невикористаний бандлований контент не коштує нічого. Рівень 2 залишається лаконічним, а рівень 3 додає саме один файл. Рядок „читає X, не читає Y“ у функції оцінки саме це перевіряє.
4. Скрипти замість прози: запускайте їх, не читайте
Це, можливо, найцінніша ідея у проектуванні навичок. Коли агент запускає скрипт через bash, у контекст потрапляє лише результат виконання, а вихідний код — ніколи. Заздалегідь написані скрипти також надійніші за код, створений на льоту, і завжди дають однаковий результат.
Отже, логіка running-coach знаходиться у Python, а інструкції прямо вказують агенту не чіпати вихідний код:
**Run the scripts, don't read them.** They print everything needed; every one
takes --help and most take --json. Reading their source wastes context.
Прогноз часу завершення бігу Riegel, розрахунок інтенсивності та аналіз даних виконуються за допомогою детерміністичного Python та повертають компактну відповідь. Агент координує процес та не перераховує дані заново. Порівняйте агента, який оцінює ваш темп, що є повільним, змінним та вимогливим до кількості оброблюваних даних, з агентом, який використовує калькулятор темпу та повідомляє число, що є швидким та однаковим щоразу.
5. Кожен скрипт — це справжній CLI зі спільними конвенціями
Щоб принцип „виконати, а не читати“ функціонував, агент має запускати скрипт, відкриття якого йому заборонено. Це можливо завдяки уніфікованому, самоописовому інтерфейсу, тому кожен скрипт дотримується однакових конвенцій:
- один позиційний аргумент для всього, що завжди є необхідним (відстань для планування та списків відтворення);
--data DIRу всіх випадках, щоб будь-який скрипт міг вказувати на інший кеш, що дозволяє проводити тестування офлайн та використовувати пісочниці на рівні сеансу;--jsonмайже у всіх з них, щоб результати одного скрипта могли бути використані наступним;--helpу кожному з них — це запасний варіант агента, коли він не впевнений щодо певного параметра. Він читає текст допомоги, що є дешевим, а не вихідний код, який є дорогим та недоступним.
Ось огляд можливостей, по одній за одною.
Планування виконання використовує plan_run.py:
python3 scripts/planning/plan_run.py 8 # 8 km, defaults
python3 scripts/planning/plan_run.py 8 --band steady # force an effort band
python3 scripts/planning/plan_run.py 8 --start-in 3 # start 3h from now (weather-aware)
python3 scripts/planning/plan_run.py 8 --json # machine-readable plan
Єдиний обов’язковий аргумент — це distance_km. Додаткові флаги — --exp, який коригує експоненту втоми Рігеля, та --band, який встановлює певний діапазон зусиль. Якщо жодних параметрів не вказано, програма визначає діапазон на основі попереднього навантаження бігуна. Хеуристична частина забезпечує свободу у прийнятті рішень, тоді як точне прогнозування залишається детерміністичним.
Плейлист обробляється файлом build_playlist.py, який навмисно імітує структуру планувальника:
python3 scripts/playlist/build_playlist.py 8 # size to the 8 km finish
python3 scripts/playlist/build_playlist.py 8 --genre "lo-fi"
python3 scripts/playlist/build_playlist.py 8 --minutes 55 # size by time instead
python3 scripts/playlist/build_playlist.py 8 --band hard
Оскільки обидві процедури займають однакову кількість часу, ці функції поєднуються: час завершення, який прогнозує plan_run, дорівнює тривалості, необхідній build_playlist для створення плейлисту. Скрипт генерує запит, а не плейлист, і агент передає цей запит до конектора Spotify. Тут знову проявляється розділення обов’язків: скрипт виконує арифметичні операції, а агент здійснює введення-виведення даних.
Щотижневий огляд — це невелика система обробки даних, а не моноліт. run_pipeline.py перевіряє кеш, а потім виконує два етапи:
python3 scripts/digest/run_pipeline.py # validate → analyse → render
python3 scripts/digest/run_pipeline.py --plan-km 8 # lead the digest with a planned run
python3 scripts/digest/run_pipeline.py --seed 3 # pin the masthead title choice
python3 scripts/digest/run_pipeline.py --skip-validate # skip the pre-flight cache check
Під ним analyze.py об’єднує збережені дані тижня в один файл digest_data.json, а build_email.py перетворює цей JSON на самодостатній HTML-лист. Розділення аналізу та форматування дозволяє змінювати вигляд листа без впливу на процес аналізу, а параметр --seed забезпечує відтворюваність єдиного випадкового вибору — заголовка верхньої частини листа, що зручно для двократного зроблення скріншотів того самого тижня.
Планування тижня — це найцікавіший інструмент командного рядка, оскільки це ланцюжок дій «планування, перевірка, виконання», виражений у вигляді підкоманд, які агент виконує у певній послідовності:
python3 scripts/planning/plan_week.py goal # show the weekly goal in force
python3 scripts/planning/plan_week.py propose # propose the split of runs (as JSON)
python3 scripts/planning/plan_week.py draft --split - # lay the split across the days
python3 scripts/planning/plan_week.py brief --draft - # hand the agent a per-run contract
python3 scripts/planning/plan_week.py events --draft - --content - # emit calendar blocks
Кожен етап виводить JSON, який наступний етап отримує через stdin. У відповідних випадках етапи також приймають поширені параметри перевизначення (--km, --runs) та опції планування, такі як --start-date, --time, --weekend-time, --location та --tz. Рекомендації пропонують саме таку форму „перевірюваних проміжних результатів“ для критичних завдань: агент ніколи не створює план від руки. Він генерує структурований план, скрипт його перевіряє та форматує, і лише після цього він перетворюється на календарні події.
На певному етапі відбувається навмисний перехід. На стадії brief скрипт розраховує відстань, діапазон темпу та день, а потім надає агенту контракт для кожної експедиції. Агент пише слова, які звучать як людські, щоб описи експедицій не були однаковими. Скрипт відповідає за те, що має бути точним, а модель — за те, що має звучати як написане. Низька свобода для складних математичних розрахунків та висока свобода для прози — це принцип „відповідних ступенів свободи“ в одному командному запиті.
6. Вирішуйте проблеми, не відкладайте їх
Слабкі навички призводять до того, що складні випадки передаються агенту з нечіткими вказівками на кшталт „якщо дані виглядають застарілими, щось з цим зробіть“. У Anthropic формулювання полягає у тому, щоб вирішувати проблеми, а не відкладати їх: потрібно обробляти ситуації з помилками у скрипті та не делегувати це іншим. running-coach застосовує цей підхід за допомогою моделі свіжості. Для кожної частини даностей у кеші він фіксує її вік, а status вказує точний запит MCP, який допоможе усунути кожну прогалину:
python3 scripts/cache.py status # what's cached, how stale, what to call
python3 scripts/cache.py put streams --file - # ingest an MCP response from stdin
python3 scripts/cache.py show week --json # a compact summary, not the raw blob
python3 scripts/cache.py validate --for digest # shape-check before a run
cache.py містить чотири функції (status, put, show, validate), кожна з яких є етапом у процесі оновлення даних. Функція status виводить список усіх ключів разом із їхнім лімітом свіжості: для поточного тижня цей ліміт є дуже обмеженим, оскільки він змінюється після кожного запуску, а для завершених тижнів та даних спортсменів — щотижня; у разі наявності застарілих чи відсутніх даних вона виводить конкретний інструмент MCP, який потрібно використати. Агент виконує цей виклик та передає отриману відповідь безпосередньо до функції put. Потім функція validate --for <capability> перевіряє, чи результат придатний до використання, перед тим як запустити наступну скриптову програму, тож некоректне отримання даних зупиняється відразу з помилкою, а не проявляється як пошкоджений звіт пізніше.
Додаткові захисні заходи: функція put приймає лише ключі з фіксованого списку дозволених значень, функція show виводить лише короткий огляд, а не сирі дані у форматі JSON, тож перевірка кешу не призводить до виведення мегабайта даних GPS у контекст, а агент отримує вказівку не редагувати ці файли JSON вручну. У результаті агенту не потрібно вирішувати, чи потрібно оновити дані чи що саме завантажувати, адже це визначено скриптом. Неоднозначне судження (“Чи достатньо ці дані свіжі?”) перетворюється на чітку інструкцію, що саме має на увазі запуск команди cache.py status перед обробкою даних.
7. Межі обробки облікових даних
Це центральний архітектурний вибір, а також захід безпеки: перевірка на наявність неочікуваних мережевих викликів та моделей доступу до файлів. Ця функція зробляє таку перевірку простою за своєю структурою, оскільки всередині неї ніщо не зберігає облікові дані та не відкриває сокети.
agent --(Strava / Spotify / AccuWeather MCP)--> cache.py put --> the cache
the cache --> plan_run.py / run_pipeline.py / build_playlist.py --> output
Тільки агент спілкується з конекторами MCP, а cache.py самостійно записує дані у кеш. Усі інші скрипти лише обробляють дані з кешу офлайн, без використання HTTP-клієнта, без API-ключів та без токенів доступу в усьому пакеті.
# cache.py — the only gateway to the running-coach data cache.
# The agent is the only thing that talks to MCP; this script is the only thing
# that reads or writes the cache. Nothing here needs an access token.
Існують три переваги. Щодо безпеки, немає нічого, що могло б витекти, а поверхня мережі для аудиту є порожньою. Щодо портативності, цей інструмент не залежить від того, чи є з’єднувачі локальними, віддаленими чи відсутніми, оскільки він використовує лише кеш. Щодо тестування, наявність заповненого кешу дозволяє кожному скрипту працювати повністю офлайн, що уможливлює виконання простих тестів у системі CI.
8. Одна вимога до середовища виконання: Python 3.10
Інструменти не синхронізуються між різними поверхнями, і кожна з них має власні обмеження щодо середовища виконання. API Claude не надає доступу до мережі та можливості встановлення пакетів, тоді як Claude Code має все необхідне. Щоб інструмент працював у будь-якому місці, потрібно проектувати його з урахуванням найбільш обмеженого середовища.
Саме тому running-coach не використовує жодних зовнішніх ресурсів. Не існує файлу requirements.txt, ні virtualenv, ні етапу встановлення. У його інструкціях зазначено, що достатньо Python 3.10 або новішої версії, і простий python3 працює без змін, навіть у хостованій сандбоксі, де неможливо встановлювати пакети.
Усе, що потрібно для цієї навички, знаходиться у каталозі skills/running-coach/. Поміщення цієї папки у ~/.claude/skills/ забезпечує роботу Claude Code, а завантаження у форматі zip — роботу Cowork або claude.ai, причому поведінка буде ідентичною. У всіх шляхах використовуються прямі слушки, що дозволяє уникнути проблем, характерних для різних платформ. Файли кешу та результатів зберігаються поза каталогом навички, що робить встановлену копію лише для читання, і вони ніколи не додаються до git, оскільки кеш містить справжні полілінії GPS, які декодуються у маршрути, що починаються біля вхідних дверей людини.
9. Перевірки упаковки та інструменти CI, які підтверджують твердження
Упаковка — це крок, який люди ігнорують. Неправильно налаштована навичка проявляється у непомітних проблемах: архів із вільними файлами у корені тихо відхиляється під час завантаження. Тому проект містить package.py — валідатор без залежностей, який повторює перевірки з власного репозиторію навичок Anthropic. Він перевіряє дозволені ключі frontmatter, ім’я у форматі kebab-case, що збігається з назвою каталогу, довжину опису в межах специфікації (з попередженням щодо приблизного ліміту у 200 символів на Claude.ai) та архів, який містить рівно один каталог верхнього рівня із файлом SKILL.md у корені.
GitHub Actions потім блокує кожну версію на основі цих перевірок. Коли піднімається тег v*, робочий процес:
- byte-compiles кожен скрипт (
python -m compileall) для виявлення синтаксичних помилок; - перевіряє frontmatter на відповідність специфікації;
- запускає кожну точку входу з параметром
--help, що принаймні показує, що кожен скрипт імпортує та обробляє дані за допомогою чистої версії Python 3.10; - перевіряє, чи знаходиться файл
running-coach/SKILL.mdу корені архіву; - і лише після всього цього публікує zip-архів.
# 3.10 is the version the skill claims to support, so building on it is
# also how that claim stays honest.
- uses: actions/setup-python@v5
with:
python-version: "3.10"
Уроки, які можна застосувати загалом
Під час розробки виділяється кілька ключових моментів:
Опис складається приблизно з 100 токенів, які виконують 90% роботи. Оскільки саме ця частина завжди завантажується, її некоректна робота робить усе інше непотрібним. Необхідно приділити їй особливу увагу та додати перевірки, які перевіряють правильність її функціонування, не згадуючи назву навички.
Перенесіть логіку з запитів у детерміністичні скрипти. Текст, який читає агент, є мінливим та коштує токенів, тоді як скрипт, який він виконує, є дешевим та завжди дає однакову відповідь. Головне — виконувати, а не читати.
Довіряйте правилам, які можна сформулювати одним реченням. Фраза «Лише агент спілкується з MCP, один скрипт записує кеш, усе інше працює офлайн» має більшу цінність, ніж купа захисного коду, адже цілі категорії помилок та витоків стають структурно неможливими.
Нехай процес збірки перевірить ваші твердження. Навичка, яка обіцяє підтримку Python 3.10 та відсутність залежностей, має будуватися саме так у середовищі CI під час кожного випуску. Без цього обіцянка залишається лише надією.
Сама кінцева мета залишається недосягнутою, але тепер існує «тренер», який планує тиждень, дає чесний огляд у понеділок вранці та щотижня перераховує ціль на основі пройденого відстані. Біг перетворився на розв’язувану інженерну проблему, як тільки його почали розглядати саме так.
Кожному, хто встановлює таку навичку, потрібно увімкнути виконання коду та власний коннектор Strava, оскільки навичка не містить жодних облікових даних. Те саме стосується джерел, які варто прочитати: огляд Agent Skills від Anthropic та сторінка з кращими практиками створення навичок, обидві знаходяться у документації Claude Platform.
Пов’язана література
- Gemini Spark: пояснення, завдання, навички, графіки, безпека та ціни — що робить цей постійно активний агент Gemini Spark від Google у Gmail, Календарі та Docs, як працюють його механізми безпеки, скільки він коштує, де його блокують та хто повинен його використовувати.
- Розширений підхід RAG у продакшені: архітектура, інструменти та компроміси — огляд використання RAG у реальних умовах: отримання даних, їх обробка, розділення на частини, створення ембеддингів, зберігання векторів, гібридні методи пошуку, переранжування результатів, оцінка ефективності та забезпечення безпеки, разом із компромісами кожного з цих підходів.