Arc OS Docs Open in app →

Створення Skills

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

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

Arc OS постачається з 40+ generic-навичками у 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))".

Skill = trigger-matched, а не always-on

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

Що таке Skill

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

skills/
├── _registry.json              ← Центральний реєстр
├── my-new-skill/
│   ├── skill.md                ← Що має робити AI
│   ├── my-new-skill.evals.json ← Як валідувати вивід
│   └── references/             ← Контекстні документи
└── library/
    └── domain-expert.md        ← Прості однофайлові skills

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

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

Шаблон

# 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)

Рівні серйозності

Приклад

{
  "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"
    }
  ]
}

Поради

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

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

Додай запис

{
  "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 бали кожен): Сигнали прямого виклику. Користувач явно хоче цей skill.

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

Рекомендації

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

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

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

Це одиничні .md файли. Без директорії, без evals, без references. Підходить для skills, орієнтованих на знання, з мінімальною валідацією.

Чекліст

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

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. Файл на диску — source of truth для контенту; DB — швидкий індекс для matching + авто-ін'єкції. Синхронізуються через seeder-скрипти.

Generic 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.

Специфічні seeders

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

Перевірка

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

owner_project = NULL → global (бачать усі проєкти). owner_project = 'my-project' → project-only (тільки той проєкт).

Project-only vs global навички

Тип навички owner_project Use case
Global (template) NULL Generic-методологія (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 навичку.