Практычныя прытамулкі: Шасць вядомых тэхналогічных компаній саюзна стварылі плагін для AI Agent

У гэтым керавану парадоксальна дорага ад сыр'ёў да рабочай системы для: Шасць вядомых тэхналогічных компаній саюзна стварылі стандарт пакавання плагіну для AI-агента пасля MCP і SKILL. Акцэнт ставіцца на крокі, якія можна выконваць, чыстае перакананне і код, які можна проста дадзіць у репозытарый без неабяснення меты. Для адгледжэння, перш чым зменяць код, неабходна визначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аператары должны магчымае перадзеісцаваць крок з вядомага пункта контролю без неабяснення схованага стану. Запісваюць час выконання і кост токеноў або запытаў разам з функцыйнальнымі рэзултатамі. Відразы костаў з самага пачатку запобегае неспадзянаным рахункам, калі дорага пераходзіць з дэмаверсіі ў спакульнаныя сераўысы.

Структура дырэктарыяў

Калі працуеце з структурой каталогаў, спачатку запішыце умовы викорыстання: неабходныя даны, сігнал успеху і тое, што выходзіць пад частым невяскам. Такі список контроля дапамагае залічыцца з пазнейшымі змянамі ў кодзе. Храніце настройкі парадульна ад коду прыемліка. Файлы сераўнавання, храненні секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аудыт без неабяжнага чытання всей структуры. Запішыце назву інструмента, хэш параметраў, час адклікання і рынак кожнага вызову. Без такога лёгкага следу дэбагаванне можа зайняць гады.

reports-plugin/
├── plugin.json                  # Required: The only entry point for the plugin
├── skills/                      # Optional: Collection of skills
│   ├── summarize/               # One individual skill
│   │   ├── SKILL.md             #   Required: Skill definition file
│   │   ├── scripts/             #   Optional: Scripts used by the skill
│   │   │   └── analyze.sh
│   │   └── references/          #   Optional: Reference documentation for the skill
│   │       └── checklist.md
│   ├── deploy/                  # A second skill
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── rollback.sh
│   │   └── references/
│   │       └── runbook.md
│   └── code-review/             # A third skill
│       └── SKILL.md
├── mcp.json                     # Optional: MCP server configuration
├── com.cursor.tools/            # Optional: Cursor-specific extensions, other clients skip automatically
│   └── hooks/
│       └── hooks.json
├── LICENSE
└── CHANGELOG.md

Спецыфікацыя plugin.json

Калі працуеце з спэкыфікацыяй plugin.json, спачатку запісайте умовы викорыстання: неабяжлівыя параметры, сігнал успеху і тое, што выканаецца у разе частковага няўспэху. Такі список контролю дапамагае заліцварыць пазнейшыя змены ў кодзе. Дакументавайце як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія перакрыцця і обробка некоректных паведамленняў є частью продукту, а не пазнейшым дапрацоўкам. Зявляйце логі з назвай інструмента, хэшам параметраў, часам адклікання і рэзультатам кожнага вызову. Без такога следу дэбагаванне можа зайняць гады.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}

Адкрыцье складовых

Калі працюеце над процэсам адкрыцья складовых, спачатку запішыце умовы ўгоды: неабходныя данні, сигнал успеху і тое, што выканаецца у разы частковага невяспамі. Такі список контролю дапамагае заставіць пазнейшыя змены коду быць чыстымі. Волейце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, невяспа должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг задач. Запішыце назву інструмента, хэш параметраў, час адклікання і рынак кожнага вызову. Без такога следу дэбагаванне губіць гады. Калі працюеце над процэсам адкрыцья складовых, спачатку запішыце умовы ўгоды: неабходныя данні, сигнал успеху і тое, што выканаецца у разы частковага невяспамі. Такі список контролю дапамагае заставіць пазнейшыя змены коду быць чыстымі. Запісвайце часы выканання і кост токенаў або запытаў разам з функцыйнальнымі рынакамі. Візуабілізація костоў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўсы.

Канфігурацыя MCP

MCP канфігурацыя працюе наўзяй калі яе спрыяваць як мерыемую структуру. Зберагучы адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу ўжытку. Хавайте канфігурацыю за межамі коду прыемліка. Файлы сераўнавальных сэрвісаў, хранілішчы секрэтных дадзеных і пазнакі функцый должны знаходзіцца ў адном месцы, куды аператары можаць адбавіць контроль без неабяжнага чытання всей структуры. Адкройце інструменты з вузкімі схемамі та чысткімі пазначэннямі побачных эфектаў. Хостам неабходна знаты, якія вызовы мутуюць стан, перш чым яны автаматычна схваляюць іх.

Зменныя сераўнавальных сэрвісаў і стойкасць дадзеных

Зменныя сераўіса і падтрымка данных працуюць наякша, калі іх спрыяваць як мерыемую структуру. Запісаўце адна ідеальная транскрыпцыя, адзін прыклад неудачы і прыметкі па абратанню наявных змян пры расшырэнні масштаба. Дакументавайце як успешны, так і вярнучы паты. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў є часткай продукту, а не наступным этапам дапрацоўкі. Адкройце інструменты з вузкімі схемамі та чыткімі пазначэннямі побачных эфектаў. Хостам неабходна знаты, якія вызовы мутуюць стан, перш чым яны будуць автаматычна затверджаны.

Ізольаваныя частковыя неудачы

Ізольаваныя частковыя аберанціі працуюць найэфективней, калі іх спрыявае можлівасць вимеры. Зберагачыце адны ідеальны прыклад роботы, адзін кейс аберанціі і прыметкі па вярнэнню да пачатковага стану пры розшырэнні масштаба. Валіце прывялёваныя, тэставальныя елементы замест большых скрыптов. Калі якісь крок не выйшае, аберанцыя должна вказываць на адну конкрэтную адпаведнасць, а не на заплутаны ланцюг задач. Адкройце інструменты з вузкімі схемамі та чысткімі пазначэннямі побачных наследкаў. Адпаведальныя за эксплуатацыю должны знать, якія вызовы мутуюць стан системы, прытаму яны можаць автаматычна санкціонаваць ўпрыем дадзеных. Ізольаваныя частковыя аберанціі працуюць найэфективней, калі іх спрыявае можлівасць вимеры. Зберагачыце адны ідеальны прыклад роботы, адзін кейс аберанціі і прыметкі па вярнэнню да пачатковага стану пры розшырэнні масштаба. Запісвайце часы выконання і вартасць токенаў або запытав, падаючы іх рядом з функцыйнальнымі рэзултатамі. Відразувыя даны пра вартасці запобегаюць неспакойным рахункам, калі процес пераходзіць з дэмовай среды ў спяльныя сераўеры.

Нез’явленыя аспекты

Для некрытых зон неабямо паказаць вхідныя даны, абонента крока і критэрыі завершэння пры змяне коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан. Конфігурацыю трэба зберагаць паза кодам прыемліка. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг. Автентыфікуйцеся на шлюзе і паўторна автарызуйцеся на роўні дадзеных. Толькі токэн-носіцель не є межай абонента.

Падтрымальнікі і відсутныя

Для падкіх даць і тых, хто не прысутны, пярэд зменым коду неабходна ясная ваказка пра інпуты, адміністратара крока і крэтэрыяванняя для завершэння. Аперацыяныя працавнікі павінны магчымае запускаць крок з вядомай точкі контролю, не прабуючы спадароўваць сабе закрыты стан. Неабходна адначасова задокументаваць шлях успеху і шлях вярнення. Перапрыбуткі, людзкія контрольныя пункты і обработка некоректных паведамленняў ёсць часткай продукту, а не елементамі пазнейшага дапрацоўвання. Аутентыфікацыя павінна выконвацца на воратах, а пераправенне праваў — на роўні дадзенаў. Толькі токен-носіцель не ёсць межай адпаведнага тэнанту.

Прыклад з рэальнага жыцця: Полны працоўны процес з Google Agents CLI

Для прыклада з рэальнага жыцця: у цэлым рабочым процесе з Google Agents CLI, пры змене коду, неабяжна практычна ваказаць інпуты, адпаведальнага за крок і крэтарыя выходу. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшаў, прычына нехасабності должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцоўкі задач. Автентыфікуйцеся на входзе і практычна перавыдайце разрэшэння на роботу з дадзеннямі. Толькі токэн-носіцель не є межай адпаведальнасці. Для прыклада з рэальнага жыцця: у цэлым рабочым процесе з Google Agents CLI, пры змене коду, неабяжна практычная ваказаць інпуты, адпаведальнага за крок і крэтарыя выходу. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан. Запісвайце час выконання і кост токэна або запыту разам з функцыйнымі рэзультатамі. Відразлівае практычна ведаць пра косты запобегае неспакоўным рахункам, калі траекторыя выконання зменяецца.

Для дэмаверыя ў спадзеленыя среды.

Связаныя лінкі

Калі працуеце з Связанымі лінкамі, спачатку запісайце умовы: неабяжлівыя данні, сигнал успеху і тое, што выходзіць пад частым неудачам. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Зберагаюце настройкі паза кодам прыемлі. Файлы среды, храненні секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адрабоўваць перагляд без неабяжлівага чытання всей структуры. Запісуйце назву інструмента, хэш параметраў, час адпаведзі і рынак кожнага вызову. Без такога следу дэбаггін агента губіць гады.

Чек-ліст для эксплуатацыі

Чек-ліст для эксплуатацыі працюе найэфектывней, калі яго спрыяваць як мерыямую плошчу. Зафіксавайце адну ідеальную транскрыпцыю, адзін прыклад неудачы і прыметку па адвярненню роботы, прытым як толькі расширяйце сферу. Спрыявайце гэты этап як умовы між вхіднымі даннымі і перакананымі выходнымі рынкамі. Назвайце артыфакты, задаць перакананні успеху і адмовіцеся ад тыхняго частага, неконтрольаванага завершэння.

Адаптавайце інструменты з вузкімі схемамі та чыткімі пазначэннямі побачных наследкаў. Хостам неабходна знаты, якія вызовы мутуюць стан, прытаму яны можаць автаматычна санкціонаваць іх.

Забяжыце адзінолюдны санкціонавань няў тых операциях, якія витрачаюць грошы або зменяюць даны ў працэсе.

Напішыце кароткі посібнік: як роцыяваць клучы, як спрачысці очакванню запытоў, як анулюваць пярэдніе дзеянні.

Документавайце як правільны, так і альтернатыўны паходы рашэння. Праказы, адзінолюдныя перакрыцця та обробка непрацэсаваных паведамленняў є часткай продукту, а не дадатковым удосконаленнем.

Перш чым пераводзіць стэк у вышэйшую версію, заморозьце ўсія версіі, зафіксавайце ідеальны прымер дзеянняў для критычных сцэнарыёў та паказвайце крокі анулювання. У спадзеленых средах неабходны ліміты частоты запытоў, перакрыцця прав на выкарыстоўвання ресурсаў та чысткі власнік для роцыявання секрэтных данных. Валіце простую надзейнась над крэатыўнымі, але разовымі дэманстрацыямі.

Запіскі для пакета 6e2f83d3e5dc: не класты ключі прадаўцоў у репазітарыю, задаць максымальны ліміт токена на кожную сесію, а таксама зберагчы транскрыпціі празаўсюды з фікстурамі для ацэнкі, каб пазнейшыя замены моделяў заставаліся порównаннэй.