Як зрабіць добры навык для Claude Agent: урокі праекта бегавога трэнера
Як пабудаваць надзейны навык 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.
Прогназаванне часу завершэння гонкі, расчытак дыяграмы навантажэння і аналіз дакладнай інфармацыі выкананы на 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 дазволяе павтараць аднаковы выбор аднойчы, тым самым з’яўляецца можлівасць два разы зробіць скрыншот таго ж тыдня.
Планаванне тыдня — гэта найцікавейшы CLI-інструмент, таму што ён выступае як поток «планаванне → перакананне → адкананне», выражаны ў відпаведных падкамандах, якія агент выпалняе па парадку:
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.
Існуе тры наступныя перавагі. Чыстаўкі безпекі — няма нічага, што магло бы выцекнуць, а паверхня сеткі для аўдыту ўсталявана. Чыстаўкі портатыбнасці — спэцыялізацыя не залежыць ад таго, чыяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяяя
Самэтна прычына, чаму 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, name у фармаце kebab-case, які падходзіць да назвы каталогу, дыявжыну апісання ў межах стандарту (з паведамленнем пра ліміт прыблізна 200 сімвалаў у claude.ai), а таксама архіў, які мае роўна адні каталог вышэйшага рэвэля з SKILL.md у корэні.
GitHub Actions пасля чаго контролюе кожны выпуск на адпаведнасць гэтым перакантрольванням. Калі падае тэг v*, працэс:
- byte-compiles кожны скрыпт (
python -m compileall) каб з’явіць сінтаксічныя памылкі; - пераканалівае фронтматэр на адпаведнасць спецыфікацыі;
- запускае кожную точку входу з параметрам
--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, адколі навык не несе жадных аутантыкацыйных даных. Тое ж самае стосуецца і джэрэл, якія варта прачытаць: аптаварыс Anthropic пра Agent Skills і старонка з наяўнымі стандартамі стварэння навыкаў, обая знаходзяцца ў документах Claude Platform.
Супаўязаныя матэрыялы
- Gemini Spark: адказанне, задачы, навыкі, графік, безпека і цены — Калі працюе агент Gemini Spark ад Google у Gmail, Календары і Docs, як функцыонуюць яго механізмы безпекі, скількі гэта коштае, дзе ён заблокаваны і каму варта яго адналожыць.
- Развітая тэхнологія RAG у працэйнай асяроддзі: архітэктура, інструменты і компромісы — Аналіз тэхнологіі RAG у практычных умовах: працэсы імпорту, парсінгу, разбівання на часткі, стварэння вектарных прэдставленняў, хранення вектараў, гібрыдныя методы пошуку, пераранжавання рэзультатаў, ацэнка эфектыўнасці і захавання даных, а таксама компромісы, якія супакоўваюцься пад час ўжыцця кожнага з этых методаў.