Skip to content

skills-evolution-roadmap.md

Latest commit

 

History

History
451 lines (302 loc) · 36.6 KB

skills-evolution-roadmap.md

File metadata and controls

451 lines (302 loc) · 36.6 KB

Skills Evolution Roadmap — запозичення з ecosystem-у agent skills

Last validated: 2026-06-14 by Claude (drift reconcile: PR 4/10/11 merged #2925; PR 7 superseded by central eval harness). Next review: 2026-08-11. Status: Active (proposal — sequencing only; кожен пункт окремий PR із власним acceptance criteria)

Що це. Курований план, як еволюціонувати repo-owned skill-систему Sergeant (.agents/skills/**) запозичивши перевірені патерни з широкого agent-skills ecosystem-у — без розмиття існуючих 12 specialist-skill-ів і без імпорту generic-обгорток. Документ працює як roadmap для будь-якого AI-агента (Claude Code, Devin, Codex, Cursor, Gemini CLI), що візьметься за конкретний пункт.

Не ініціатива в docs/90-work/initiatives/ через audit-freeze 2026-05-05 → 2026-06-02. Якщо post-freeze команда вирішить підняти це в формальну initiative-у з owner-ом і ETA — створити docs/90-work/initiatives/00NN-skills-evolution.md і перенести скоуп туди; цей файл тоді стає секцією ## Sources в новій initiative-і. До того часу — це discovery roadmap, не зобов'язання.

Що ми НЕ робимо. Не запускаємо npx @agentskill.sh/cli@latest setup. Не ставимо generic-скіли у .claude/skills/. Не дублюємо agentskills.io open standard 1:1 — наш lang/lang-reason frontmatter і UA/EN bilingual routing-формат лишаються (PR #1848). Це строго import-of-patterns, не import-of-content.

Контекст і джерела

Огляд проведено 2026-05-10 за запитом @Skords-01 (session). Перевірено три зрілі точки референсу:

Джерело Що дає License
agentskills.io open standard Формальна schema для SKILL.md frontmatter; 3-tier progressive disclosure; reference-file convention з impact: + tags:. open standard
anthropics/skills Reference patterns: scripts/ як black-box, references/ для деталі, evals/ для quantitative тригер-тестів, "pushy" описи. Apache-2.0
supabase/agent-skills 28 Postgres reference-файлів за 8 категоріями (query-, schema-, lock-, data-, monitor-, conn-, security-, advanced-). MIT
obra/superpowers (130k★) 14 process-skill-ів (brainstorming, TDD, systematic-debugging, verification-before-completion, receiving-code-review, …). (per-file)
agentskill.sh directory Маркетплейс ~107k SKILL.md + server-side security scanner на 12 категорій загроз. (per-skill)

Повний log джерел і їх якості — у session-transcript-і вище. Не імпортуємо звідти SKILL.md як-є — ми еволюціонуємо власну skill-систему, відштовхуючись від цих практик.

Принципи відбору

PR проходить у roadmap, якщо він задовольняє всі чотири:

  1. Не дублює існуючий Sergeant skill. Якщо sergeant-bugfix-and-regression уже каже "reproduce-first, failing check first" — додавання obra/systematic-debugging як окремого скілу буде redundant. Замість цього адаптуємо ідею в існуючий skill.
  2. Не залежить від зовнішнього сервісу. Sergeant — local-first/private. PR не має додавати dependency на agentskill.sh CLI, зовнішні API, чи плагінні маркетплейси.
  3. Сумісний з 21 hard rule. Якщо патерн суперечить (наприклад, generic React-скіл, який ігнорує RQ keys factory) — pass.
  4. Має конкретний acceptance criterion. Не "поліпшити DX", а "після PR pnpm lint:skills падає, якщо description: коротший за N символів і не містить тригер-фрази X".

PR-послідовність

Дев'ять незалежних PR-ів, від найдешевшого до найдорожчого. Кожен — окремий branch, окремий PR, окремий verify-step. Один PR на одну проблему (Hard Rule #15 sub-clause). Ніяких bundled-changes.

Drift policy. Якщо план відстає реальності, фіксуй це errata-блоком у цій секції з датою і коротким поясненням, як у docs/90-work/initiatives/0011-…md. Не переписуй мовчки, не видаляй "невзяті" пункти.

Errata 2026-06-14 (Claude). Reconcile зі станом репо: PR 4 / 10 / 11 змерджено одним commit f0581fa8e у #2925 (2026-05-16) — статуси оновлено з «in progress» на ✅; усі три скіли (sergeant-e2e-testing, sergeant-security-audit, sergeant-tech-debt) уже в .agents/skills/ і в routing-таблиці AGENTS.md. PR 7 (Skill evals substring) — superseded: централізований harness docs/00-start/agents/skill-trigger-evals.json + pnpm eval:skills уже покриває 2 trigger + 1 anti-trigger + 1 workflow-compliance prompt на кожен repo-owned skill (ширше за per-skill evals/evals.json із початкового плану) і вшитий у pnpm lint:skills. Окремий PR 7 не беремо. PR 8 (real-LLM runner) залежав від PR 7 → переоцінити проти наявного harness-у, а не від нуля.

PR 1 — Pushy descriptions audit (≈30 хв, S) ✅ (merged: #2374, 2026-05-10)

Проблема. Claude і інші LLM-агенти undertrigger-ять скіли, якщо description: стримане. У anthropics/skill-creator явно сказано: опис має містити "Make sure to use this skill whenever the user mentions X, Y, Z, even if they don't explicitly ask".

Скоуп.

  • Прочитати всі 12 description: у .agents/skills/*/SKILL.md.
  • Для кожного перевірити проти трьох питань: (а) чи перелічено триггер-фрази з реальних задач? (б) чи містить "use when …" + "use also when …"? (в) чи є UA-тригер-фраза для bilingual routing (як у sergeant-start-here)?
  • Вивести diff і узгодити з owner-ом перед merge — це behavior-shaping content, не cosmetics.

Acceptance criteria.

  • Кожен з 12 description: ≥ 200 символів і ≤ 1024 (agentskills.io limit).
  • Кожен містить ≥ 3 тригер-фрази/контексти.
  • Кожен містить UA-фразу (як ; UA: …).
  • pnpm lint:skills лишається зеленим (shape + integrity).
  • Опційно: розширити pnpm lint:skills гейтом description.length >= 200. Якщо так — зафіксувати ескалацію severity у hard-rules.json як sub-clause до Rule #10 (lifecycle markers) або як новий "skill description quality" rule (нова active-initiative; не blocker до runs of evals у PR 7).

Files touched.

  • .agents/skills/*/SKILL.md (12 файлів — frontmatter only).
  • .agents/skills-lock.json (regenerate via pnpm skills:lock).
  • Опційно: scripts/lint-skills.mjs (якщо вирішимо додати length-check).

References.

PR 2 — Verification-before-completion gate в sergeant-review-and-merge (≈2 год, S) ✅ (merged: #2373, 2026-05-10)

Проблема. Жоден з 12 Sergeant skill-ів не містить explicit-гейту "не клейми completion без свіжого verification-evidence". sergeant-review-and-merge фокусується на contract-checks і scope, але не на дисципліні language-у ("Should pass now", "I'm confident"). Це — найдешевший quality bump з усього roadmap-у.

Скоуп.

  • Додати в sergeant-review-and-merge/SKILL.md нову секцію "Verification gate" з Iron Law формулюванням і Red Flags таблицею (адаптовано з obra/superpowers/verification-before-completion).
  • Додати в sergeant-bugfix-and-regression/SKILL.md посилання на цей gate як обов'язковий перед "Done".
  • Узгодити з PR template (.github/PULL_REQUEST_TEMPLATE.md § Verification вже містить command-block — Iron Law доповнює його).

Acceptance criteria.

  • Секція додана; містить (а) Iron Law-формулювання "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE", (б) Red Flags-таблицю на ≥ 5 випадків ("tests pass" / "linter clean" / "build succeeds" / "bug fixed" / "regression test works"), (в) явну заборону формулювань "Should pass" / "Looks correct" / "I'm confident" перед прогоном.
  • pnpm lint:skills зелений; pnpm skills:lock оновлено.
  • Cross-link з sergeant-bugfix-and-regression ("Перед claim 'fixed' — Verification gate в sergeant-review-and-merge").

Files touched.

  • .agents/skills/sergeant-review-and-merge/SKILL.md
  • .agents/skills/sergeant-bugfix-and-regression/SKILL.md
  • .agents/skills-lock.json

References.

PR 3 — Postgres reference-rules в sergeant-data-and-migrations (≈2 год, M)

Проблема. sergeant-data-and-migrations enforce-ить sequential numbering і two-phase DROP, але не покриває generic Postgres performance pitfall-и (FK без index-у, n+1, missing partial index, deadlock-prone update order, vacuum starvation). У supabase/agent-skills ці правила вже структуровані як reference-файли з impact: + EXPLAIN-прикладами + GOOD/BAD SQL.

Скоуп.

  • Створити .agents/skills/sergeant-data-and-migrations/references/ (нова конвенція 3-tier disclosure).
  • Адаптувати 9 reference-файлів (не 28 — берем тільки релевантне Sergeant-у; решта або supabase-specific, або не зачіпає реальні query-патерни в apps/server):
    • query-missing-indexes.md
    • query-partial-indexes.md
    • query-composite-indexes.md
    • schema-foreign-key-indexes.md — Postgres не індексує FK автоматично.
    • data-batch-inserts.md
    • data-pagination.md
    • data-n-plus-one.md
    • lock-skip-locked.md
    • monitor-pg-stat-statements.md
  • У основному SKILL.md додати посилання-блок: "Для performance/index/lock-питань див. references/{prefix}-*.md".
  • Зберегти Sergeant-specific шари: bigint coercion (Hard Rule #1), Kyiv time, sequential migrations (Hard Rule #4) — це наша надбудова, не замінюється Supabase rules.

Acceptance criteria.

  • 9 reference-файлів за форматом agentskills.io (title:, impact: CRITICAL|HIGH|..., impactDescription:, tags:).
  • Основний SKILL.md ≤ 500 рядків після рестру (більшість performance-вмісту переїде в references/).
  • pnpm lint:skills адаптовано перевіряти references/*.md shape (frontmatter required + scope check).
  • pnpm skills:lock хешує всю директорію скілу включно з references/.
  • Кожен reference-файл містить (а) "Incorrect" SQL з поясненням чому погано, (б) "Correct" SQL з поясненням чому добре, (в) Sergeant-specific нотатку якщо є (наприклад, у query-missing-indexes згадати наші bigint-серіалізатори).

Files touched.

  • .agents/skills/sergeant-data-and-migrations/SKILL.md (slim).
  • .agents/skills/sergeant-data-and-migrations/references/*.md (9 нових).
  • .agents/skills-lock.json.
  • scripts/lint-skills.mjs (extension для references/).

References.

PR 4 — sergeant-e2e-testing skill (≈2 дні, M) ✅ (merged: #2925, 2026-05-16)

Проблема. Sergeant використовує Playwright для E2E (див. apps/web test-stack), але немає specialist-skill-у про Playwright-discipline. sergeant-web-ui згадує a11y і design tokens, але golden-rules для Playwright (web-first assertions, fixtures over globals, traces='on-first-retry', retries=2-in-CI/0-locally, ніколи page.waitForTimeout()) — розкидані по PR-описах і не enforce-ні.

Скоуп.

  • Створити .agents/skills/sergeant-e2e-testing/SKILL.md.
  • Тригер-описи: "Playwright тести, E2E, snapshot regression, accessibility automation, MSW + Playwright integration".
  • Body: 8 golden rules (адаптовано з testdino-hq/playwright-skill + obra/superpowers/test-driven-development для red-green-refactor частини).
  • references/:
    • selectors.md — preferred locators (role > text > testid; уникати nth-child).
    • network-mocking.md — коли мокати, коли ні; інтеграція з MSW.
    • auth-flow.md — Better Auth login fixture (Sergeant-specific).
    • traces-and-debugging.md — 'on-first-retry', --ui mode.
  • Оновити agent-skills-catalog.md і sergeant-start-here/SKILL.md (роутинг-таблиці).

Acceptance criteria.

  • Скіл проходить pnpm lint:skills і додано в skills-lock.json.
  • Routing-рядок у sergeant-start-here для сценарію "Playwright / E2E / smoke test".
  • Жодне правило skill-у не суперечить існуючим apps/web Playwright-конфігам — якщо є невідповідність, спочатку фіксимо конфіг окремим PR.
  • Опційно: pnpm test:e2e (якщо є alias) посилається на skill в README як "guidelines see .agents/skills/sergeant-e2e-testing".

Files touched.

  • .agents/skills/sergeant-e2e-testing/SKILL.md + references/*.md.
  • .agents/skills/sergeant-start-here/SKILL.md (routing-таблиця).
  • .agents/skills-lock.json.
  • docs/00-start/agents/agent-skills-catalog.md (новий рядок).

References.

PR 5 — Security body-scan як гейт у pnpm lint:skills (≈1 день, M) ✅ (merged: #2378, 2026-05-10)

Проблема. pnpm lint:skills зараз перевіряє shape (frontmatter, links) + integrity (SHA-256 ↔ skills-lock.json). Не перевіряє body на injection-патерни. agentskill.sh запровадив сервер-side static analysis на 12 категорій загроз після широковідомого OpenClaw-інциденту; це доцільно мати як local CI-gate теж.

Скоуп.

  • У scripts/lint-skills.mjs додати body-scanner, що шукає підозрілі патерни:
    • Команд injection: літеральні curl … | sh, wget … | bash, eval $(, \...`` в інструкціях, що пропонує агенту виконати arbitrary HTTP-результат.
    • Data exfiltration: cat /etc/passwd, читання ~/.ssh/id_*, читання .env файлів і HTTP-POST з ними.
    • Credential harvesting: інструкції відкривати ~/.aws/credentials, ~/.config/gcloud/, browser cookie storage.
    • Prompt injection: теги <system>, <persona>, що намагаються переписати system-prompt агента.
    • Persistence: crontab, systemctl enable, ~/.bashrc editing без user-prompt-у.
    • Reverse shells: nc -e, bash -i >& /dev/tcp/*.
    • Destructive: rm -rf /, git reset --hard, git clean -fd без guard-у.
  • Запустити сканер проти всіх 12 існуючих skill-ів — зафіксувати baseline (очікую 0 hits, але треба перевірити).
  • Додати unit-тести для сканера (scripts/__tests__/lint-skills-scan.test.mjs).
  • Як behavior-shaping content тут немає, severity = error із самого початку (не warning).

Acceptance criteria.

  • Сканер ловить ≥ 7 категорій загроз з регресійних fixture-ів у scripts/__tests__/fixtures/malicious-skills/.
  • Прогін на 12 існуючих skill-ів дає 0 hits (clean baseline).
  • pnpm lint:skills падає на synthetic malicious skill-фікстурі.
  • Розділ "Skill body security" додано в docs/04-governance/governance/rules/ — або як sub-clause до Rule #10, або як нова Rule #22 (active-initiative, deadline 2026-Q3).
  • Якщо нова Hard Rule — оновити hard-rules.json, hard-rules-matrix.md, AGENTS.md table; pass pnpm lint:hard-rules-registry.

Files touched.

  • scripts/lint-skills.mjs.
  • scripts/__tests__/lint-skills-scan.test.mjs + fixtures/malicious-skills/*.md.
  • docs/04-governance/governance/hard-rules.json (якщо нова rule).
  • docs/04-governance/governance/hard-rules-matrix.md (regenerated).
  • docs/04-governance/governance/rules/22-skill-body-security-scan.md (опційно).
  • AGENTS.md Hard rules table (опційно).

References.

  • agentskill.sh — категорії загроз (12 категорій: command injection / data exfiltration / credential harvesting / prompt injection / persistence / sensitive file access / external calls / reverse shells / destructive commands / social engineering / obfuscation / supply-chain).
  • OpenClaw incident — search-tag: "OpenClaw skills attack 2025" (sources: agentskill.sh blog, Koi.ai writeup; конкретний URL зафіксувати на момент PR-у).
  • Існуючий docs/04-governance/governance/rules/07-pre-commit-hooks-via-husky.md — формат hard-rule файлу.

PR 6 — Reference-folder convention як сторінка governance (≈1 год, S)

Проблема. Якщо PR 3 (Postgres references) і PR 4 (e2e references) внесуть references/ у два скіли, треба canonical опис: коли робити reference-файл, як називати, які frontmatter-поля обов'язкові. Без цього через 6 місяців отримаємо drift (один скіл — references/{prefix}-*.md, інший — refs/*-{name}.md).

Скоуп.

  • Додати секцію "Reference files convention" у docs/00-start/agents/agent-skills-catalog.md (або винести в окремий docs/00-start/agents/skill-authoring-guide.md).
  • Оригінальний body-skill ≤ 500 рядків; деталі — у references/{prefix}-{name}.md.
  • Frontmatter obligatory: title, impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW, impactDescription, tags: [...].
  • Body: "Incorrect (description)" SQL/code → "Correct (description)" SQL/code → optional Sergeant-specific нотатки.
  • Розширити pnpm lint:skills валідацією references/ shape.

Acceptance criteria.

  • Документ у docs/00-start/agents/ із прикладом (адаптована sample-сторінка зі stop-skip locked).
  • pnpm lint:skills перевіряє reference-frontmatter shape і зелений на baseline.
  • Cross-link з agent-skills-catalog.md на цю секцію.

Files touched.

  • docs/00-start/agents/skill-authoring-guide.md АБО розширення docs/00-start/agents/agent-skills-catalog.md.
  • scripts/lint-skills.mjs.
  • docs/00-start/agents/README.md (додати рядок у table).

References.

PR 7 — Skill evals: quantitative trigger-testing (≈2 дні, L) ⛔ superseded (див. Errata 2026-06-14 — реалізовано централізованим harness-ом)

Проблема. Зараз ми не маємо способу перевірити чи правильно тригериться скіл. pnpm lint:skills перевіряє shape, але не behavior. Якщо хтось зламає description: (PR 1 робить його pushy → потім хтось downgrade-ить), не дізнаємось доки агент не помиляється у проді.

Скоуп.

  • Створити .agents/skills/<skill>/evals/evals.json для 3 priority-skill-ів: sergeant-start-here, sergeant-feature-delivery, sergeant-bugfix-and-regression.
  • Кожен файл — 5–7 prompt-ів ({ "id": …, "prompt": "…", "expected_skill": "…", "must_match": [...], "must_not_match": [...] }).
  • Expected-skill assertion — простий substring-checker, без real-LLM-запиту (тестуємо routing-table в sergeant-start-here і description-тригери, не runtime-LLM).
  • Опційно (post-PR): runner з реальним LLM-запитом → відкладено в PR 8.
  • Додати команду pnpm test:skill-evals що прогоняє shape + routing-checker.

Acceptance criteria.

  • 3 skill-и мають evals/evals.json з ≥ 5 prompt-ів кожен.
  • pnpm test:skill-evals зелений локально + CI.
  • Якщо хтось редагує description: так, що eval-prompt більше не тригерить очікуваний skill — гейт падає.
  • Документ у docs/00-start/agents/skill-authoring-guide.md (PR 6) розширено інструкцією про evals.

Files touched.

  • .agents/skills/{sergeant-start-here, sergeant-feature-delivery, sergeant-bugfix-and-regression}/evals/evals.json.
  • scripts/test-skill-evals.mjs.
  • package.json (scripts.test:skill-evals).
  • CI-workflow (.github/workflows/skill-freshness.yml — додати step або новий workflow).

References.

PR 8 — Real-LLM eval runner (опційно, ≈2 дні, L) — POST-FREEZE

Проблема. Substring-eval-checker (PR 7) не ловить ситуації, коли два скіли тригеряться одночасно або жоден. Реальний LLM-запит — точніший, але дорогий.

Скоуп.

  • Runner запускає Claude/GPT з prompt-ом + всіма 12 description-ами як tools і дивиться, який tool вибрав.
  • Variance analysis: 5 runs per prompt (LLM варіативний).
  • Бюджет: ≤ $5/run всього suite (~50 prompts × 5 runs × ~200 tokens).
  • Дзвінки опт-in (тільки за pnpm test:skill-evals --real-llm); CI запускає тільки на main після merge, не на PR.

Acceptance criteria.

  • pnpm test:skill-evals --real-llm працює локально проти ANTHROPIC_API_KEY чи OPENAI_API_KEY env.
  • Звіт варіативності pinned в .agents/skills/<skill>/evals/results-baseline.json.
  • CI-cron (weekly) запускає suite і додає issue-comment у тред initiative-и, якщо routing accuracy < 90%.

Files touched.

  • scripts/test-skill-evals.mjs (extension).
  • .agents/skills/*/evals/results-baseline.json (нові).
  • CI workflow (новий cron-job).

References.

PR 9 — verification-before-completion як cross-link з PR template (≈30 хв, S) ✅ (merged: #2375, 2026-05-10)

Проблема. PR 2 додає Iron Law у sergeant-review-and-merge. Але людина-контриб'ютор не обов'язково читає skill-и. PR template вже має чек-лист "Verification" з командами — треба явно лінкувати на skill-секцію.

Скоуп.

  • Один рядок у .github/PULL_REQUEST_TEMPLATE.md § Verification: "Перед claim-ом 'Done' — Iron Law gate з sergeant-review-and-merge, секція 'Verification gate' (додана в PR 2)".
  • Один рядок у docs/00-start/agents/onboarding.md § "Перед PR" — те саме посилання.

Acceptance criteria.

  • PR template містить посилання, що резолвиться у відрендереному UI GitHub-у.
  • pnpm docs:check-links зелений.

Files touched.

  • .github/PULL_REQUEST_TEMPLATE.md.
  • docs/00-start/agents/onboarding.md.

PR 10 — sergeant-security-audit skill (≈1 день, M) ✅ (merged: #2925, 2026-05-16)

Проблема. Sergeant має Hard Rules #20 (PAT safety), #21 (Pino redaction), #22 (skill security scan) і playbook security-pen-test-checklist.md, але немає specialist-skill-у, що веде агента через security review. Агент без цього skill-у системно пропускає Sergeant-specific вектори: перевірку REDACT_KEY_NAMES у @sergeant/shared/lib/pii.ts, Drizzle sql\...`injection,pnpm audit(неnpm audit`) для workspace-монорепо.

Скоуп.

  • Створити .agents/skills/sergeant-security-audit/SKILL.md.
  • Покрити: Hard Rules #20/#21/#22, Pino redaction walker у apps/server/src/obs/logger.ts, Drizzle ORM SQL injection vector, pnpm audit, Better Auth session enforcement, frontend TypedStore, mobile MMKV, severity triage.
  • Оновити agent-skills-catalog.md і routing у sergeant-start-here.

Acceptance criteria.

  • pnpm lint:skills зелений (shape + SHA-256 + security scan).
  • Routing-рядок у sergeant-start-here для "Security review, pnpm audit, PAT safety".
  • Кожна секція посилається на конкретний шлях у репо або команду.

Files touched.

  • .agents/skills/sergeant-security-audit/SKILL.md.
  • .agents/skills/sergeant-start-here/SKILL.md (routing-таблиця).
  • .agents/skills-lock.json.
  • docs/00-start/agents/agent-skills-catalog.md.

References.

  • aitmpl.com: security/security-auditor, security/api-security-audit, security/supply-chain-security — натхнення для структури, адаптовано під Sergeant-specific hard rules.

PR 11 — sergeant-tech-debt skill (≈1 день, M) ✅ (merged: #2925, 2026-05-16)

Проблема. 26 hard rules визначають taxonomy технічного боргу, але немає specialist-skill-у, що систематично веде агента через eslint-baseline.js, Knip, Hard Rule #18 (module-size), Hard Rule #19 (noUncheckedIndexedAccess). Агент без цього skill-у міксує різні класи боргу в один PR або видаляє код без перевірки lifecycle markers.

Скоуп.

  • Створити .agents/skills/sergeant-tech-debt/SKILL.md.
  • Покрити: eslint-baseline.js (25 rules, 9 disabled react-hooks v7), Knip lifecycle marker guards, module-size decomposition strategy (Hard Rule #18), noUncheckedIndexedAccess guards (Hard Rule #19), prioritization matrix, "окремі PRs для різних класів боргу" правило.
  • Оновити agent-skills-catalog.md і routing у sergeant-start-here.

Acceptance criteria.

  • pnpm lint:skills зелений.
  • Routing-рядок у sergeant-start-here для "Технічний борг, dead code, ESLint baseline".
  • Чітке правило: не змішувати dead-code deletion, baseline reduction і module decomposition в одному PR.

Files touched.

  • .agents/skills/sergeant-tech-debt/SKILL.md.
  • .agents/skills/sergeant-start-here/SKILL.md (routing-таблиця).
  • .agents/skills-lock.json.
  • docs/00-start/agents/agent-skills-catalog.md.

References.

  • aitmpl.com: development-tools/technical-debt-manager — натхнення для структури аудиту; адаптовано під Sergeant's eslint-baseline.js і Knip замість generic complexity-метрик.

Priority matrix

# PR Effort Value-per-hour Dependencies Status
1 Pushy descriptions audit S High none ✅ #2374
2 Verification gate in review skill S Highest none ✅ #2373
3 Postgres references M High (no hard dep)
4 E2E testing skill M Medium (no hard dep) ✅ #2925
5 Security body-scan in lint:skills M High none ✅ #2378
6 References folder convention S Medium depends on PR 3 / 4
7 Skill evals (substring) L Medium-High depends on PR 1 ⛔ superseded
8 Real-LLM eval runner L Medium depends on PR 7
9 PR template cross-link S High depends on PR 2 ✅ #2375
10 sergeant-security-audit skill M High none ✅ #2925
11 sergeant-tech-debt skill M High none ✅ #2925

Recommended starting order: PR 2 → PR 1 → PR 5 → PR 9 (merged) → PR 4 / 10 / 11 (merged #2925) → PR 3 → PR 6 (єдині відкриті) → PR 7 (superseded) → PR 8 (переоцінити). Тобто лишилися тільки PR 3 (Postgres references) і залежний від нього PR 6 (references-convention governance page).

Найдешевший quality-bump: PR 2 (Verification gate) — лінгвістична дисципліна, що ловить 60-70% "Should pass now" / "Looks correct" хибних completion claims одним прочитанням SKILL.md.

Anti-scope (що ми НЕ робимо)

  • npx @agentskill.sh/cli@latest setup. Цей CLI ставить /learn команду + опційно дамп generic-скілів у .claude/skills/. Конфліктує з нашою policy "не покладайся на repo-owned обгортки generic-skill-ів" (sergeant-start-here) і ламає hash-lock дисципліну.
  • Імпорт generic-skillset-ів (GreenXred/Front-dev, Hoaiduc195/Backend). Конфліктує з RQ keys factory, design tokens, Hard Rule #2/#8/#9.
  • OpenClaw-derived скіли (openclaw/feishu-*, openclaw/xurl, openclaw/voice-call). Tool wrapper-и для зовнішніх сервісів поза стеком; багато мають security-аудит-issues (acp-router: 3 high + 6 medium).
  • anthropics/frontend-design. "Bold aesthetic direction, avoid Inter font" — суперечить нашому design-tokens-system.
  • Supabase RLS skills. У нас Better Auth + opaque IDs, а не Postgres RLS — рекомендації не translate-ються.
  • Перейменування існуючих skill-frontmatter-полів під 1:1 agentskills.io standard. Ми лишаємо lang: + lang-reason: (PR #1848) — це bilingual-routing, не cosmetics.

Tracking

Цей документ — discovery roadmap, не active initiative. PR-и можна брати в довільному порядку (з урахуванням dependencies в матриці вище). Якщо post-freeze (≥ 2026-06-02) команда вирішить підняти це у формальну initiative-у з owner-ом і ETA — створити docs/90-work/initiatives/00NN-skills-evolution.md і перенести скоуп з цього файлу. До того часу:

  • При закритті PR — додати рядок у "PR-послідовність" вище: (merged: #NNNN, YYYY-MM-DD).
  • При drift — додати errata-блок із поясненням.
  • Next review: дата зверху bump-ається при кожному значущому update-і.

See also