Версия: ИИ спец релиз

Пользовательские навыки

Пользовательский навык описывается в виде текстового файла в формате Markdown с блоком метаданных YAML в начале. Системные навыки TRON.ASOC написаны по единой структуре; пользовательские навыки рекомендуется оформлять так же — это упрощает проверку и использование результата навыка в условиях переходов автоматизации.

Структура файла навыка

Текстовый файл с навыком имеет следующую структуру (см. таблицу ниже).

Раздел	Обязательность	Содержание
Метаданные (YAML)	Обязательно	Название, описание, версия, категория и уровень риска навыка (подробнее см. раздел Метаданные навыка)
Заголовок	Обязательно	Название навыка на русском языке
Назначение	Обязательно	Что делает навык, что он не делает и выполняет ли он изменяющие действия
Быстрый старт	Рекомендуется	Краткая сводка: входные данные, шаги, результат
Предусловия	Обязательно	Условия, при которых навык может быть выполнен: входные данные, права пользователя, наличие подтверждения
MCP-инструменты	Обязательно	Таблица операций, которые использует навык
Алгоритм	Обязательно	Пронумерованные шаги от проверки входных данных до формирования результата
Пограничные случаи	Обязательно	Таблица нештатных ситуаций и итогового статуса для каждой из них
Запрещено	Обязательно	Полный перечень действий, которые навык не должен выполнять

Метаданные навыка

Описание метаданных, отображаемых в YAML-блоке в начале файла, представлено в таблице ниже.

Поле	Описание	Пример
`name`	Уникальный идентификатор навыка. Латиница в нижнем регистре, слова через дефис, формат «действие-объект».	`deduplicate-issues`
`description`	Одно-два предложения: что делает навык и в какой ситуации его применять. Вторую часть рекомендуется начинать со слов «Используй, когда…».	`Применяет дедупликацию к предоставленному списку уязвимостей ASOC. Используй, когда автоматизация уже определила дубликаты…`
`version`	Версия навыка в формате `MAJOR.MINOR.PATCH`.	`1.0.0`
`category`	Категория навыка.	`issue-management`, `external`
`risk_level`	Уровень риска: выполняет ли навык изменяющие действия.	`write`

Принципы создания навыков

При создании навыков руководствуйтесь следующими принципами:

Одна задача — один навык. Навык решает только одну ограниченную задачу. Если задача включает этап принятия решения и этап выполнения действия, разделите их на два навыка. Например, стандартный навык deduplicate-issues только применяет дедупликацию, а поиск дубликатов выполняет отдельный навык find-duplicate-issues, который стоит в автоматизации шагом раньше. Так проще проверять результат каждого шага и настраивать переходы между ними.
Прямо укажите, чего навык не делает. В разделе «Назначение» укажите границы навыка (например: Навык не ищет дубликаты и не решает, какие уязвимости являются дубликатами). Этот принцип снижает риск того, что модель выйдет за пределы задачи.
Не допускайте домыслов. На первом шаге алгоритма соберите входные данные в виде JSON-структуры и проверьте обязательные поля. Если данных не хватает, навык должен завершиться с ошибкой, а не подбирать значения самостоятельно. Добавьте в инструкцию прямой запрет на те или иные действия.
Проверяйте объекты перед изменением. Перед изменяющей операцией прочитайте целевые объекты операцией на чтение (например, asoc_get_issue) и убедитесь, что они существуют и соответствуют входным данным.
Запрашивайте подтверждение перед изменяющим действием. Если навык изменяет данные, добавьте в алгоритм отдельный шаг с подготовкой данных для подтверждения: тип действия и ключевые параметры. Без полученного подтверждения навык завершается с ошибкой. Исключение — случай, когда автоматизация явно разрешает выполнение без подтверждения.

Внимание
Шаг подтверждения в тексте навыка не заменяет системную проверку. Независимо от содержания инструкции, каждое изменяющее действие проходит проверку прав (RBAC) и политики подтверждений. Подробнее см. раздел Контроль действий и подтверждений.
Ограничьте набор инструментов. Указывайте в таблице MCP-инструментов только те операции, которые действительно используются в алгоритме. Для каждой операции укажите следующие данные:
- приоритет: при required навык не работает без операции, при optional навык используется для дополнительных проверок;
- уровень риска: read или write;
- статус доступности операции в текущей версии TRON.ASOC.
Навык не может запрашивать операции за пределами допустимого набора, а навыки с изменяющими операциями требуют одобрения администратором.
Возвращайте структурированный результат. Последний шаг алгоритма всегда формирует результат единого формата (см. раздел Формат результата). Поля результата используются в условиях переходов автоматизации, поэтому не меняйте их названия и типы без повышения версии навыка.
Сообщайте об ограничениях. Если навык не может выполнить задачу полностью, опишите это в поле limitations. Например, стандартный навык update-pull-request не может изменить pull request во внешней Git-системе напрямую и вместо этого фиксирует обновление комментарием к уязвимости — это ограничение явно указано в результате.
Пишите инструкцию в повелительном наклонении. Формулируйте шаги короткими командами, а ветвления — в формате «условие → действие»:

Если master_issue_id отсутствует:

Верни `failed`.

Вызовы операций приводите в блоках кода с именами параметров.

Формат результата

Навык возвращает объект со следующими полями (см. таблицу ниже).

Поле	Описание
`status`	Итоговый статус выполнения: `success`, `partial` или `failed`.
`approval`	Сведения о подтверждении: `required` — требовалось ли подтверждение, `approved` — получено ли оно.
`evidence`	Подтверждающие данные: список вызванных операций (`mcp_tools`), идентификаторы обработанных объектов, исходный ответ изменяющей операции (`raw_response`).
`result`	Предметный результат навыка. Состав полей зависит от задачи.
`limitations`	Список ограничений, из-за которых задача выполнена не полностью или иным способом. Пустой список, если ограничений нет.

Используйте статусы следующим образом (см. таблицу ниже).

Статус	Когда использовать
`success`	Все шаги алгоритма выполнены полностью.
`partial`	Действие выполнено для части объектов: например, часть уязвимостей не найдена или часть операций завершилась ошибкой.
`failed`	Нет обязательных входных данных, целевой объект не найден, не пройдена проверка, не получено подтверждение, отказано в доступе (`403`) или изменяющая операция завершилась ошибкой.

Шаблон навыка

Скопируйте шаблон и замените значения в угловых скобках. Если навык не изменяет данные, удалите разделы, отмеченные комментарием .

---
name: <action-object>
description: >
  <Что делает навык, одним предложением.>
  Используй, когда <в какой ситуации и на каком шаге автоматизации применять навык>.
version: 1.0.0
category: <категория>
risk_level: <read|write>
---

# <Название навыка>

## Назначение

<Что делает навык и над какими объектами.>

<Из каких данных навык исходит: какой предыдущий шаг `workflow` или какой ввод пользователя их предоставляет.>

Скилл **не** <что навык не делает: не ищет, не решает, не генерирует>.

<!-- только для write -->
Скилл выполняет write-действия и требует подтверждения, если родительский `workflow` явно не разрешает автоматическое выполнение.

---

## Быстрый старт

```text
Input: <поле_1>, <поле_2>
Steps: проверка входа → проверка объектов → подтверждение → <действие> → возврат результата
Output: <что возвращает навык>
```

---

## Предусловия

- <Какие входные данные должны быть предоставлены.>
- У пользователя есть право <на какое действие>.
- Получено подтверждение, если родительский `workflow` явно не разрешает автоматическое выполнение. <!-- только для write -->

---

## MCP-инструменты

| Приоритет | Инструмент | Назначение | Риск | Статус |
|---|---|---|---|---|
| required | `<asoc_operation>` | <Назначение> | <read\|write> | <Статус> |
| optional | `<asoc_operation>` | <Назначение> | read | <Статус> |

---

## Алгоритм

### 1. Нормализовать вход

Собери:

```json
{
  "<поле_1>": "uuid",
  "<поле_2>": ["uuid"]
}
```

Если `<поле_1>` отсутствует:

Верни `failed`.

Не выдумывай <идентификаторы и значения, которые не были переданы>.

---

### 2. Проверить объекты

```text
<asoc_read_operation>(<поле_1>)
```

Если объект не найден:

Верни `failed`.

Если часть объектов не найдена:

Верни `partial`.

---

### 3. Проверить входные данные

Проверь:

- <правило валидации 1>;
- <правило валидации 2>.

Если валидация не проходит:

Верни `failed`.

---

### 4. Запросить подтверждение <!-- только для write -->

Подготовь payload подтверждения:

```json
{
  "action": "<action_name>",
  "<ключевой_параметр>": "<значение>"
}
```

Если подтверждение не получено:

Верни `failed`.

---

### 5. <Выполнить действие>

Вызови:

```text
<asoc_write_operation>(
  <параметр>=<значение>
)
```

Сохрани сырой ответ в `evidence.raw_response`.

Если часть операций завершилась ошибкой:

Верни `partial`.

---

### 6. Собрать результат

Верни:

```json
{
  "status": "success|partial|failed",
  "approval": {
    "required": true,
    "approved": true
  },
  "evidence": {
    "mcp_tools": ["<asoc_operation>"],
    "<поле_1>": "uuid"
  },
  "result": {
    "<поле_результата>": "<значение>"
  },
  "limitations": []
}
```

---

## Пограничные случаи

| Ситуация | Поведение |
|---|---|
| <Объект не найден> | `failed` |
| <Часть объектов не найдена> | `partial` |
| <Подтверждение не получено> | `failed` |
| Отказ в доступе (`403`) | `failed` |

---

## Запрещено

- Исполнять write-операции без явного подтверждения пользователя, если родительский `workflow` явно не разрешает автоматическое выполнение.
- <Действия за пределами назначения навыка.>
- Выдумывать <идентификаторы, данные> или результат выполнения.
- Обходить RBAC.

Проверка навыка перед публикацией

Перед сохранением навыка в системе убедитесь, что навык соответствует следующим условиям:

name уникален и отражает действие навыка;
description описывает, когда применять навык;
навык решает одну задачу, а его границы явно указаны в разделе Назначение;
все операции из алгоритма перечислены в таблице MCP-инструментов, и в таблице нет лишних операций;
для каждого обязательного входного поля есть проверка и ветка failed;
перед каждой изменяющей операцией есть проверка объектов и шаг подтверждения;
для каждой ветки алгоритма, которая завершается failed или partial, есть строка в таблице пограничных случаев;
результат содержит поля status, approval, evidence, result и limitations;
в разделе Запрещено есть запреты на домыслы и обход RBAC.

Структура файла навыка​

Метаданные навыка​

Принципы создания навыков​

Формат результата​

Шаблон навыка​

Проверка навыка перед публикацией​