Скиллы GitHub Copilot для 1С

Полная документация ниже — автоматически из репозитория andanlv-ai/1c-copilot-skills (ветка master). Оригинальные материалы проекта распространяются на условиях его лицензии.

# 1C Copilot Skills

Репозиторий GitHub Copilot Skills для разработки в 1С:Предприятие 8.2.

Содержание

1. Как пользоваться скиллами
2. Как дорабатывать скиллы
3. Как создавать новые скиллы
4. Что ещё стоит добавить

Структура репозитория

1c-copilot-skills/
├── .github/
│   └── skills/
│       ├── dev-1c/                   ← Общий скилл, любой 1С 8.2 проект
│       │   ├── SKILL.md              ← Методология, алгоритмы, шаблоны
│       │   └── references/
│       │       ├── bsl-standards.md  ← Стандарты BSL + чеклист ревью
│       │       └── mcp-1c-tools.md   ← Справочник инструментов mcp_1c
│       └── rdpi-1c/                  ← Проектный скилл (Swedbank)
│           └── SKILL.md
├── deploy.ps1                        ← Скрипт деплоя
└── README.md

Правило: этот репозиторий — единственный источник истины.
Скиллы редактируются здесь, отсюда деплоятся в проекты и в личные настройки Copilot.

Часть 1: Как пользоваться скиллами

Что такое skill

Skill — это файл инструкций (SKILL.md), который Copilot загружает по запросу.
Агент читает его и начинает действовать по описанному алгоритму.

Скиллы живут в двух местах:

• ~/.copilot/skills/ — личные, доступны во всех проектах VS Code
• <проект>/.github/skills/ — проектные, доступны только в одном воркспейсе

Как вызвать скилл

Способ 1 — явный, через /:
В Copilot Chat введи / — появится список всех скиллов и промптов.
Выбери /dev-1c или /rdpi-1c.

Способ 2 — автоматический:
Просто опиши задачу. Copilot читает поле description каждого скилла
и сам решает — нужен ли скилл для этого запроса.

Фразы, которые автоматически активируют dev-1c:

"нужно добавить фичу в 1С"
"исправить баг в BSL"
"сделай research кодовой базы"
"как написать запрос в 1С 8.2"
"ревью кода BSL"

Типичная рабочая сессия с dev-1c

Ты:      /dev-1c нужно добавить обработку нового типа операции
Copilot: [читает SKILL.md, запускает Research через mcp_1c, создаёт research.md]

Ты:      переходи к Design
Copilot: [создаёт architecture.puml, contracts.md, decisions.md...]

Ты:      Plan
Copilot: [разбивает на фазы: phase-1.md, phase-2.md...]

Ты:      реализуй фазу 1
Copilot: [пишет BSL-код → ревью стиля → ревью соответствия дизайну]

Не пропускай фазы. Каждая создаёт артефакт для следующей.
Если пропустить Design — в Implement агент начнёт угадывать архитектуру.

Разница между dev-1c и rdpi-1c

В Swedbank-проекте используй rdpi-1c — он даёт более точный контекст.

Часть 2: Как дорабатывать скиллы

Рабочий цикл доработки

1. Открой C:\Users\user\1c-copilot-skills в VS Code
2. Отредактируй нужный файл скилла
3. Задеплои:
   .\deploy.ps1 -Force                                   (только dev-1c)
   .\deploy.ps1 -ProjectPath "C:\...\проект" -Force      (+ rdpi-1c в проект)
4. Перезапусти VS Code (полностью, не reload window)
5. Проверь в Copilot Chat что скилл работает
6. git add . ; git commit -m "описание изменения"

Какой файл за что отвечает

SKILL.md — дорабатывай когда:

• Добавился новый сценарий использования
• Нужно уточнить алгоритм фазы
• Copilot делает что-то не так — добавь явный запрет
• Добавился новый тип задач (регистры, СКД, HTTP)

references/bsl-standards.md — дорабатывай когда:

• Нашёл новый типичный баг → добавь в чеклист
• Появился паттерн который нужно запретить или обязать
• Нужен новый раздел (транзакции, HTTP-запросы, COM-объекты)

references/mcp-1c-tools.md — дорабатывай когда:

• Нашёл новый инструмент mcp_1c или новый сценарий его применения

Как проверить что изменение работает

1. Открой Copilot Chat (Ctrl+Alt+I или через боковую панель)
2. Введи / → проверь что скилл виден в списке
3. Задай конкретный вопрос:
   "что делает dev-1c?"         → Copilot должен ответить по SKILL.md
   "покажи чеклист ревью BSL"   → должен дать содержимое bsl-standards.md
4. Проверь что новое правило соблюдается в генерируемом коде

Частые проблемы

Скилл не появляется в / списке:

• Имя папки должно совпадать с полем name в frontmatter — точно, без опечаток
• Файл должен называться SKILL.md (заглавными буквами)
• Перезапусти VS Code полностью

Copilot игнорирует правила скилла:

• Самые важные правила помещай в description (до 1024 символов) —
  это первое что читает агент
• В теле SKILL.md пиши конкретные, однозначные инструкции
• Используй императив: "НИКОГДА не используй X" вместо "лучше избегать X"
• Добавь примеры правильного и неправильного кода

Reference-файлы не загружаются:

• Пути в SKILL.md относительны от папки скилла: ./references/bsl-standards.md
• Не используй абсолютные пути и не выходи за папку скилла (../../)
• Агент загружает reference только если явно на него ссылается — добавь ссылку в SKILL.md

Часть 3: Как создавать новые скиллы

Принцип: один скилл = одна специализация

Не делай один большой скилл на всё. Несколько специализированных работают лучше:

Структура нового скилла

.github/skills/<имя-скилла>/
├── SKILL.md           ← Обязательный. Имя файла фиксировано — именно SKILL.md
├── references/        ← Большие блоки (чеклисты, справочники) — сюда
│   ├── topic-1.md
│   └── topic-2.md
└── assets/            ← Шаблоны кода, boilerplate — опционально
    └── template.bsl

Шаблон SKILL.md (скопируй и адаптируй)

---
name: имя-скилла
description: "Что делает одним предложением. Используй когда: задача 1, задача 2,
  задача 3. Покрывает: тема 1, тема 2. Включает: инструмент 1, шаблон 2."
argument-hint: "Подсказка что написать при /имя-скилла"
---

# Название

Одно предложение — что делает скилл.

> ВАЖНО: ключевое ограничение или платформа.

## Когда использовать

- Триггерная фраза / ситуация 1
- Триггерная фраза / ситуация 2

## Шаг 1: Название

Что делать на этом шаге. Какие инструменты использовать.
Ожидаемый результат.

## Шаг 2: Название

...

## Правила (нарушать нельзя)

- НИКОГДА не делай X — потому что Y
- Всегда используй A вместо B

## Справочники

- Полный список → [references/topic-1.md](./references/topic-1.md)

Правила хорошего description

Description — это единственное что агент читает при обнаружении скилла.
От него зависит — загрузится скилл автоматически или нет.

ПЛОХО:  "Помогает с разработкой"
ХОРОШО: "Разработка запросов 1С 8.2. Используй когда: нужно написать
          запрос, оптимизировать выборку, написать СКД, разобраться
          с временными таблицами. Включает: шаблоны запросов, примеры
          группировок, правила работы с регистрами."

Правила:

• Максимум 1024 символа (больше — срезается)
• Включай ключевые слова из реальных запросов пользователя
• Обязательно: паттерн "Используй когда: …"
• Перечисляй конкретные технологии и термины

Три уровня загрузки (важно для структуры файлов)

Агент читает скилл поэтапно — это влияет на то куда что класть:

Уровень 1 (~100 токенов):   name + description из frontmatter
                             → решает нужен ли скилл

Уровень 2 (<5000 токенов):  тело SKILL.md
                             → понимает что делать

Уровень 3 (по ссылке):      файлы из references/ и assets/
                             → загружает только когда явно нужно

Правило:

• SKILL.md ≤ 400 строк — алгоритм + краткие правила + ссылки на references
• references/*.md — большие чеклисты, справочники, примеры кода
• assets/* — шаблоны и boilerplate

Пошаговый процесс создания скилла

Шаг 1: Определи специализацию

Ответь письменно:

• Какую конкретную задачу решает скилл (одно предложение)?
• Какие слова напишет пользователь когда ему нужен этот скилл?
• Что агент должен делать шаг за шагом?
• Какие правила нельзя нарушать?

Шаг 2: Собери знания до написания

• Алгоритм действий (пронумерованные шаги)
• Инструменты (команды, функции, API)
• Запрещённые паттерны с примерами
• Шаблоны / boilerplate кода

Шаг 3: Распредели материал по файлам

В SKILL.md:          алгоритм + краткие правила + ссылки на references
В references/:       чеклисты > 30 строк, справочники, примеры > 20 строк
В assets/:           шаблоны кода, boilerplate

Шаг 4: Напиши description последним

После того как написал тело SKILL.md — возьми все ключевые слова из него
и включи в description. Description — это "рекламный текст" скилла для агента.

Шаг 5: Добавь в deploy.ps1

В файл deploy.ps1 добавь строку для нового скилла:

Deploy-Skill -SkillName "имя-нового-скилла" -DestinationBase $PersonalSkillsPath -Force:$Force

Шаг 6: Протестируй

1. .\deploy.ps1 -Force
2. Перезапусти VS Code
3. Проверь появление в / списке
4. Напиши запрос без упоминания скилла — активировался автоматически?
5. Проверь что агент следует инструкциям из SKILL.md
6. Если нет — уточни description или добавь правила в тело SKILL.md

Часть 4: Что ещё стоит добавить

Улучшения текущего dev-1c

• [ ] Раздел: работа с регистрами накопления (остатки, обороты, запросы)
• [ ] Раздел: работа с регистрами сведений (срезы, периодичность)
• [ ] Раздел: разработка отчётов в 8.2 (обычные отчёты, СКД)
• [ ] Раздел: работа с HTTP-соединениями в 8.2 (HTTPSоединение)
• [ ] Раздел: транзакции (НачатьТранзакцию, правила отката)
• [ ] Раздел: работа с COM-объектами (Excel, Word через COM)
• [ ] В bsl-standards.md: типовые шаблоны запросов с временными таблицами
• [ ] В bsl-standards.md: правила работы с блокировками данных

Улучшения текущего rdpi-1c

• [ ] Описание XML-структуры факторинговых файлов (теги, вложенность)
• [ ] Список всех кодов типов операций CSV с описанием обработки
• [ ] Реквизиты документов конфигурации (ПлатежноеПоручениеВходящее и др.)
• [ ] Описание всех процедур ИмпортИзСведбанк.bsl (краткий справочник)

Новые скиллы для создания

Деплой — быстрая справка

# Задеплоить dev-1c в личные скиллы Copilot (все проекты)
.\deploy.ps1

# Задеплоить dev-1c + rdpi-1c в конкретный проект
.\deploy.ps1 -ProjectPath "C:\Users\user\мой-проект"

# Принудительное обновление (перезаписать существующие)
.\deploy.ps1 -ProjectPath "C:\Users\user\мой-проект" -Force

# После деплоя — перезапустить VS Code полностью

Активация в Copilot Chat

/dev-1c   → общий скилл 1С 8.2 (всегда доступен после deploy.ps1)
/rdpi-1c  → проектный скилл Swedbank (только в том воркспейсе куда задеплоен)

Или просто опиши задачу — Copilot подберёт нужный скилл по ключевым словам.