Створення скілів

Покроковий посібник з додавання нової експертизи до твого проєкту Arc OS.

Перш ніж писати новий скіл — перевір глобальну бібліотеку

Arc OS постачається з 40+ універсальними скілами в skills/, що покривають поширені ролі. Перш ніж створювати новий, подивись, чи наявні вже покривають твою потребу:

Домен	Доступні скіли
Engineering	`commit-discipline`, `tdd-flow`, `react-best-practices`, `postgres-patterns`, `mcp-builder`
Frontend / Design	`frontend-design-principles`, `svg-graphics`, `slide-deck-html`, `service-design`, `scss-modular-architecture`, `responsive-mobile-first`
Startup ops	`market-analysis`, `gtm-strategy`, `financial-modeling`, `pitch-deck`, `customer-development`, `fundraising`, `founder-brand`, `metrics-dashboard`, `legal-startup`
Marketing	`seo-foundations`, `founder-brand`
Process	`standup-aggregator`, `commit-discipline`
Database	`postgres-patterns`

Переглянь повний список: GET /api/crm/skills?category=<X> або bun -e "console.log(JSON.stringify(require('./skills/_registry.json').skills.map(s=>s.name),null,2))".

Скіл = trigger-matched, не always-on

Скіл авто-інжектується в промт воркера, коли повідомлення збігається з його triggers (у _registry.json). Поле description — це логіка тригера ("коли це використовувати"), а не summary. Context Router обирає топ-5 збігів на кожне повідомлення.

Що таке скіл

Скіл — це портативний набір інструкцій, який навчає твого AI-бота конкретної здатності. Скіли живуть у каталозі skills/ і складаються з:

<name>.md — файл інструкцій (обов'язковий)
<name>.evals.json — правила автоматичної валідації якості (необов'язково, але рекомендовано)
references/ — допоміжні документи, схеми, приклади (необов'язково)

skills/
├── _registry.json              ← Central registry
├── my-new-skill/
│   ├── skill.md                ← What the AI should do
│   ├── my-new-skill.evals.json ← How to validate the output
│   └── references/             ← Context documents
└── library/
    └── domain-expert.md        ← Simple single-file skills

Крок 1: напиши skill.md

Це основна інструкція. Claude читає її, коли скіл активовано.

Шаблон

# Skill Name

## Purpose
What this skill accomplishes in one sentence.

## When to Use
- Trigger condition 1
- Trigger condition 2

## Protocol
1. First action
2. Second action
3. Third action

## Output Format
What the response should look like.

## Constraints
- What NOT to do
- Safety boundaries

Приклад: Odoo Expert

# Odoo Expert

## Purpose
Odoo ERP module development: models, views, security, QWeb templates.

## When to Use
- Building or modifying Odoo modules
- Writing QWeb templates
- Configuring access rules and record rules
- Working with the ORM (create, write, search, browse)

## Protocol
1. Check if modifying an existing module or creating new
2. Follow Odoo 17 conventions (manifest, models/, views/, security/)
3. Use self.env['model.name'] for ORM operations
4. Always use _t() or t-call for translatable strings
5. Test with --test-tags after changes

## Constraints
- Never use cr.execute() for direct SQL — use ORM
- Never use sudo() unless security context explicitly requires it
- No inline JavaScript in QWeb templates

Крок 2: напиши evals (правила якості)

Evals — це декларативні правила, що автоматично валідують кожну відповідь. Вони виконуються після того, як Claude генерує вивід, і додають попереджувальні виноски, якщо правила не пройдені.

Іменування файлу

skills/<name>/<name>.evals.json

Схема

{
  "version": 1,
  "skill": "my-new-skill",
  "rules": [
    {
      "id": "ms-001",
      "name": "Human-readable rule description",
      "type": "rule_type",
      "value": "for string/length types",
      "pattern": "for regex types",
      "severity": "warning"
    }
  ]
}

Доступні типи правил

Тип	Що перевіряє	Використовує поле
`string_contains`	Відповідь містить літеральний текст	`value` (string)
`string_not_contains`	Відповідь НЕ містить текст	`value` (string)
`regex_match`	Відповідь збігається з regex	`pattern` (string)
`regex_not_match`	Відповідь НЕ збігається з regex	`pattern` (string)
`max_length`	Довжина відповіді <= N символів	`value` (number)
`min_length`	Довжина відповіді >= N символів	`value` (number)

Рівні severity

warning — Вказує на проблему з якістю. Показується як ⚠️.
info — Дорадча нотатка. Показується як ℹ️.

Приклад

{
  "version": 1,
  "skill": "odoo-expert",
  "rules": [
    {
      "id": "oe-001",
      "name": "Must use ORM, not raw SQL",
      "type": "string_not_contains",
      "value": "cr.execute",
      "severity": "warning"
    },
    {
      "id": "oe-002",
      "name": "Must use translation helpers",
      "type": "regex_match",
      "pattern": "_t\\(|t-call|t-esc",
      "severity": "warning"
    },
    {
      "id": "oe-003",
      "name": "Response under 5000 chars",
      "type": "max_length",
      "value": 5000,
      "severity": "info"
    }
  ]
}

Поради

Почни з 2-3 правил. Додавай більше, коли виявляєш патерни з корекцій.
Спершу безпека: string_not_contains для небезпечних команд, regex_not_match для патернів облікових даних.
Конвенція ID: <skill-prefix>-<number> (наприклад oe-001, gm-002).
Тест: Надішли повідомлення, що має тригернути скіл, перевір, чи попередження з'являються коректно.

Крок 3: зареєструй у _registry.json

Реєстр розповідає Context Router'у про твій скіл, щоб той міг рекомендувати його для релевантних повідомлень.

Додай запис

{
  "name": "my-new-skill",
  "description": "One sentence (shown in SKILLS_HINT, max 80 chars).",
  "triggers": ["direct-command", "explicit-request", "пряма команда"],
  "keywords": ["broader", "semantic", "related-term"],
  "agents": ["rick"],
  "category": ["complex"],
  "phase": "21.5"
}

Triggers vs Keywords

Triggers (по 2 бали кожен): Сигнали прямого виклику. Користувач явно хоче цей скіл.

"deploy", "review", "scaffold", "odoo", "audit"

Keywords (по 1 балу кожен): Ширші терміни, що натякають на релевантність, не будучи командами.

"OWASP", "Docker", "CI/CD", "production", "module"

Крок 4: Library Skills (простий формат)

Для доменної експертизи, якій не потрібні evals чи окремий каталог, використовуй skills/library/:

skills/library/
├── docker-ops.md
├── postgres-pro.md
└── react-patterns.md

Це одиночні .md-файли. Без каталогу, без evals, без references. Добре для скілів, насичених знаннями, з малою кількістю валідації.

Чекліст

skills/<name>/skill.md — інструкція з Purpose, Protocol, Constraints
skills/<name>/<name>.evals.json — щонайменше 2 правила валідації
Запис у skills/_registry.json — із triggers і keywords
Назва збігається всюди — назва каталогу = назва скілу в evals = назва в реєстрі
Тест: надішли тригерне повідомлення → перевір SKILLS_HINT у логах
Тест: навмисно тригерни збій eval → перевір, що з'являється попередження

Що відбувається під час виконання

1. Bot starts → loadRegistry() reads _registry.json
                 loadEvals() reads all .evals.json files
                 loadLearnings() reads learnings.md

2. Message arrives → routeContext() scores skills → SKILLS_HINT injected
                     formatForPrompt() adds LEARNINGS block

3. Claude responds → checkOutput() runs eval rules
                     formatEvalWarnings() appends footnotes

4. Fix It / thumbs-down → addLearning() writes to learnings.md
                          qualityTracker logs feedback

5. Nightly → findUnderperformingSkills() checks metrics
             Proposals sent to CEO for approval

Засівання скілів у глобальну DB

Скіли в DB (таблиця skills_global) — це SSOT для Context Router. Файл на диску — це джерело істини для вмісту; DB — це швидкий індекс для зіставлення + авто-інжекції. Вони синхронізуються через seeder-скрипти.

Універсальний seeder за категорією

# Reads skills/_registry.json, filters by category, upserts skills_global rows.
# Idempotent + drift-aware (skip if no change, update on content drift).
bun scripts/seed-skill-category.ts --category engineering
bun scripts/seed-skill-category.ts --category frontend
bun scripts/seed-skill-category.ts --category marketing

Працює для будь-якої категорії, наявної в _registry.json. Бере першу категорію з масиву як значення DB-колонки.

Специфічні seeder'и

scripts/seed-startup-skills.ts — хардкод для category="startup" (10 скілів startup-операцій)
scripts/migrate-skills-to-db.ts — історична масова міграція (усі файли, лише insert, без update)

Коли запускати

Після створення нового .md + запису в _registry.json → запусти seeder один раз
Після оновлення вмісту наявного .md → drift-aware seeder оновлює DB
Bootstrap нового проєкту → seeder'и запускаються через vps-sync.sh Step 1.5 (заплановано)

Перевірка

sqlite3 data/citadel.db "SELECT name, category, owner_project FROM skills_global ORDER BY id"

owner_project = NULL → глобальний (видимий усім проєктам). owner_project = 'my-project' → лише для проєкту (тільки цей проєкт).

Project-only vs глобальні скіли

Тип скілу	`owner_project`	Сценарій використання
Global (шаблон)	NULL	Універсальна методологія (TDD, Conventional Commits, AARRR) — корисна для будь-якого проєкту
Project-only	`'<project-name>'`	Документи, специфічні для НАШОГО кодбейсу (наприклад `crm-api-reference` живе лише в arc-v2)

Перенести наявний скіл у project-only:

sqlite3 data/citadel.db "UPDATE skills_global SET owner_project='my-project' WHERE name='internal-api-docs'"

Фільтр listForProject контролює видимість: інші проєкти не побачать project-only скіл.