{
  "markdown": "# HLD Solution Designer\n\nКросплатформний AI-скіл, який перетворює короткий опис продукту або системи на\nPresales Lite High-Level Design (HLD) у Markdown із діаграмою Mermaid. Один і\nтой самий процес працює у Claude, Codex, Claude Code та Gemini CLI на macOS і\nWindows.\n\nСкіл відокремлює підтверджені вимоги від припущень і критичних запитань. Завдяки\nцьому архітектура залишається корисною, але не подає невідомі дані як факти.\nДіаграми описують логічні компоненти, їхні обов'язки та потоки без прив'язки до\nконкретного хмарного провайдера або деталей розгортання.\n\n## Швидке встановлення для учасників воркшопу\n\nОберіть застосунок, у якому хочете працювати. Для графічних версій Claude і\nCodex не потрібні Gemini CLI, Python, Node.js або API-ключ.\n\n| Застосунок | macOS | Windows | Рекомендований спосіб |\n| --- | --- | --- | --- |\n| Claude Desktop/Web/Cowork | Так | Так | Завантажити підготовлений ZIP зі скілом |\n| Codex Desktop/CLI | Так | Так | Встановити з GitHub через вбудований `$skill-installer` |\n| Claude Code | Так | Так | Встановити репозиторій як Claude plugin |\n| Gemini CLI | Так | Так | Встановити репозиторій як Gemini extension |\n\n### Варіант A: Claude Desktop, Web або Cowork\n\nІнструкція однакова для macOS і Windows.\n\n> **Важливо:** HLD Solution Designer не опублікований у публічному каталозі\n> плагінів або скілів Claude. Завантаження ZIP створює приватний custom skill у\n> вашому акаунті Claude. Це не встановлення з Marketplace.\n\n1. [Завантажте останню версію Claude skill](https://github.com/somebodywastoldme/high-level-design-skill/releases/latest/download/ml-system-hld-claude.zip).\n   Не розпаковуйте файл.\n2. Відкрийте Claude та перейдіть до **Customize → Skills**.\n3. Натисніть **+ → Create skill → Upload a skill**.\n4. Оберіть `ml-system-hld-claude.zip` та увімкніть **HLD Solution Designer**.\n5. Створіть новий чат і вставте перший prompt із розділу\n   [Запуск демо](#запуск-демо).\n\nДля Claude Skills має бути ввімкнено **Code execution and file creation**. У\nпланах Team або Enterprise адміністратор організації також може мати потребу\nввімкнути Skills. Дивіться\n[офіційну інструкцію Anthropic](https://support.claude.com/en/articles/12512180-use-skills-in-claude).\n\nЯкщо розділу **Customize → Skills** немає, перевірте **Settings → Capabilities →\nCode execution and file creation**. У керованому Team або Enterprise workspace\nзверніться до адміністратора. Якщо Skills усе одно недоступні, скористайтеся\n[Claude Code](#варіант-c-claude-code).\n\n### Варіант B: Codex Desktop або CLI — найпростіший спосіб\n\nІнструкція однакова для macOS і Windows. Відкрийте нову задачу в Codex і\nнадішліть повідомлення:\n\n```text\nUse $skill-installer to install the skill from\nhttps://github.com/somebodywastoldme/high-level-design-skill/tree/main/skills/ml-system-hld\n```\n\nДочекайтеся завершення встановлення, а потім створіть **нову задачу Codex**, щоб\nCodex завантажив новий скіл. Викличте його через `$ml-system-hld` або вставте\nперший prompt із розділу [Запуск демо](#запуск-демо).\n\n#### Ручне встановлення Codex на macOS\n\nСкористайтеся цим способом, якщо репозиторій уже клоновано або завантажено:\n\n```bash\ncd /path/to/high-level-design-skill\nmkdir -p ~/.codex/skills\ncp -R skills/ml-system-hld ~/.codex/skills/\n```\n\nПеревірте встановлення:\n\n```bash\ntest -f ~/.codex/skills/ml-system-hld/SKILL.md && echo \"HLD skill installed\"\n```\n\n#### Ручне встановлення Codex на Windows\n\nВідкрийте **PowerShell** у папці завантаженого репозиторію та виконайте:\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\\skills\" | Out-Null\nCopy-Item -Recurse -Force \".\\skills\\ml-system-hld\" \"$env:USERPROFILE\\.codex\\skills\\\"\n```\n\nПеревірте встановлення:\n\n```powershell\nTest-Path \"$env:USERPROFILE\\.codex\\skills\\ml-system-hld\\SKILL.md\"\n```\n\nPowerShell має вивести `True`. Після ручного встановлення перезапустіть Codex\nабо створіть нову задачу.\n\n### Варіант C: Claude Code\n\nВиконайте ці команди всередині Claude Code. Вони однакові для macOS і Windows:\n\n```text\n/plugin marketplace add somebodywastoldme/high-level-design-skill\n/plugin install hld@hld-designer\n```\n\nПлагін додає команди `/hld:requirements` і `/hld:design`.\n\n## Запуск демо\n\nПрацюйте з папки проєкту, у якій потрібно створити `requirements.md` і\n`hld.md`.\n\n### Крок 1 — discovery та вимоги\n\nУ Claude або Codex вставте:\n\n```text\nВикористай HLD Solution Designer. Проведи зі мною інтерв'ю щодо B2B-платформи,\nяка отримує контракти, перевіряє їх, передає винятки спеціалістам та\nінтегрується з CRM. Підготуй requirements.md, але запиши файл лише після того,\nяк я підтверджу чернетку.\n```\n\nАсистент ставитиме по одному запитанню та розділятиме **підтверджені факти**,\n**припущення** і **невідомі дані**. Коли чернетка буде готова, підтвердьте її.\n\n### Крок 2 — архітектура\n\nУ тому самому проєкті вставте:\n\n```text\nВикористай HLD Solution Designer. Прочитай затверджений requirements.md і створи\nvendor-neutral Presales Lite HLD із Mermaid-діаграмою архітектури. Запиши\nрезультат у hld.md.\n```\n\nОчікуваний результат:\n\n- `requirements.md` — затверджені вимоги та реєстр тверджень;\n- `hld.md` — базова архітектура, Mermaid-діаграма, обґрунтування, ризики,\n  альтернативи та відкриті запитання.\n\n## Встановлення у Gemini CLI\n\nВстановіть extension безпосередньо з GitHub:\n\n```bash\ngemini extensions install https://github.com/somebodywastoldme/high-level-design-skill\n```\n\nДля локальної розробки:\n\n```bash\ngemini extensions install /path/to/high-level-design-skill\n```\n\nПеревірте встановлення:\n\n```bash\ngemini extensions list\n```\n\nУ списку має з'явитися `hld-ml-designer`.\n\nЩоб отримати нову версію після її публікації на GitHub, перезапустіть Gemini CLI\nта виконайте:\n\n```bash\ngemini extensions update --all\n```\n\n## Локальна розробка з Claude Code\n\nЩоб тестувати зміни без marketplace, запустіть Claude Code з кореневої папки\nрепозиторію:\n\n```bash\nclaude --plugin-dir .\n```\n\nПісля редагування виконайте `/reload-plugins`.\n\n## Збирання пакетів для розповсюдження\n\nУчасникам воркшопу не потрібно збирати пакети самостійно. Готові ZIP-файли\nпублікуються на сторінці\n[GitHub Releases](https://github.com/somebodywastoldme/high-level-design-skill/releases).\n\nMaintainer може перевірити складання локально на macOS або Linux:\n\n```bash\n./scripts/build-demo-packages.sh\n```\n\nСкрипт створює:\n\n- `dist/ml-system-hld-claude.zip` для ручного завантаження у Claude;\n- `dist/hld-codex-plugin.zip` для майбутньої публікації через Codex marketplace.\n\nПапка `dist/` не зберігається в Git. GitHub Actions автоматично перебудовує\nобидва ZIP-файли, створює `SHA256SUMS.txt` та прикріплює їх до GitHub Release.\n\n## Публікація нової версії через GitHub\n\nДля публікації не потрібно вручну збирати або завантажувати ZIP-файли.\n\n1. Переконайтеся, що всі потрібні зміни вже об'єднані з гілкою `main`.\n2. Відкрийте сторінку **Releases** у GitHub.\n3. Натисніть **Draft a new release**.\n4. Натисніть **Choose a tag → Create new tag** і введіть номер, наприклад\n   `v0.1.0`. Оберіть гілку `main`.\n5. У полі заголовка введіть `HLD Solution Designer v0.1.0`.\n6. Натисніть **Publish release**.\n7. Відкрийте вкладку **Actions** і дочекайтеся завершення workflow\n   **Publish skill packages**.\n\nПісля успішного workflow у Release з'являться:\n\n- `ml-system-hld-claude.zip`;\n- `hld-codex-plugin.zip`;\n- `SHA256SUMS.txt`.\n\nПосилання **Завантажте останню версію Claude skill** на початку README завжди\nведе на ZIP із найновішого GitHub Release.\n\n## Використання slash-команд\n\nУ Gemini CLI та Claude Code доступний процес із двох команд:\n\n```text\n/hld:requirements \"B2B-платформа отримує контракти, перевіряє їх, передає винятки спеціалістам та інтегрується з CRM.\"\n/hld:design\n```\n\n### Крок 1 — формування вимог\n\nЗапустіть:\n\n```text\n/hld:requirements \"система модерації завантажених зображень товарів зі швидкістю 2000 зображень на хвилину\"\n```\n\nСкіл проведе інтерактивне discovery-інтерв'ю за шістьма категоріями: бізнес-ціль,\nкористувачі, функціональний обсяг, масштаб, дані та інтеграції, безпека й\nобмеження. Після вашого підтвердження він створить `requirements.md`.\n\n### Крок 2 — створення HLD\n\nПісля затвердження `requirements.md` виконайте:\n\n```text\n/hld:design\n```\n\nСкіл створить `hld.md` із вісьмома обов'язковими розділами, логічною\nMermaid-діаграмою, базовим рішенням, компромісами, discovery-запитаннями та не\nбільш ніж двома умовними альтернативами.\n\n> Запускайте команди з папки, у якій мають знаходитися `requirements.md` і\n> `hld.md`.\n\n## Що ви отримаєте\n\n`hld.md` міститиме:\n\n- vendor-neutral логічну архітектуру;\n- читабельну Mermaid-діаграму;\n- таблицю компонентів та їхніх обов'язків;\n- зв'язок між вимогами й архітектурними рішеннями;\n- ризики, припущення та відкриті запитання;\n- базовий варіант і щонайбільше дві умовні альтернативи.\n\nMermaid-блок можна відкрити в IDE, GitHub Wiki або\n[Mermaid Live](https://mermaid.live).\n\n## Ручний smoke test\n\nПісля встановлення запустіть:\n\n```text\n/hld:requirements \"B2B-платформа отримує контракти, перевіряє їх, передає винятки спеціалістам та інтегрується з CRM.\"\n/hld:design\n```\n\nПеревірте, що:\n\n- `requirements.md` відокремлює факти, припущення та критичні запитання;\n- скіл не вигадує точний SLA або навантаження;\n- `hld.md` містить усі вісім Presales Lite розділів;\n- Mermaid-діаграма використовує vendor-neutral логічні компоненти;\n- вказано базову архітектуру, компроміси та discovery-запитання;\n- запропоновано не більше двох альтернатив;\n- немає cloud-vendor mapping або деталей рівня LLD.\n\n## Усунення проблем\n\n### Claude не показує розділ Skills\n\nУвімкніть **Settings → Capabilities → Code execution and file creation**. Для\nTeam або Enterprise зверніться до адміністратора організації. Якщо розділ не\nз'являється, використайте Claude Code.\n\n### Codex не бачить `$ml-system-hld`\n\nПереконайтеся, що існує файл:\n\n- macOS: `~/.codex/skills/ml-system-hld/SKILL.md`;\n- Windows: `%USERPROFILE%\\.codex\\skills\\ml-system-hld\\SKILL.md`.\n\nПісля встановлення створіть нову задачу Codex.\n\n### Gemini або Claude Code не показує slash-команди\n\nДля Gemini CLI виконайте:\n\n```text\n/commands reload\n```\n\nДля Claude Code виконайте:\n\n```text\n/reload-plugins\n```\n\n### Mermaid-діаграма не рендериться\n\nВставте блок `mermaid` у [Mermaid Live](https://mermaid.live), перевірте\nсинтаксис і повторно запустіть `/hld:design`.\n\n### DEMO задача для GDG\n\n```text\nМаркетплейс приймає фото товарів від продавців. Перед публікацією треба перевірити неприйнятний контент і дублікати, а сумнівні випадки передати модератору. У пікові години завантаження різко зростають. Продавець має бачити статус обробки.\n```\n",
  "bytes": 10495,
  "sha": "1cf74c75c2f03993054d6b5f778461dd43ac033dfa4d828c54191b2177b2ddeb",
  "repo_slug": "somebodywastoldme/high-level-design-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_somebodywastoldme_high_level_design_skil_1a0b7c59/readme"
}