Emmanuel Atsé
cede485217
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
6.8 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Skills | Reference BMad skills — co to je, jak fungují a kde je najít. |
|
Skills jsou předpřipravené prompty, které načítají agenty, spouštějí workflow nebo provádějí úkoly ve vašem IDE. Instalátor BMad je generuje z vašich nainstalovaných modulů při instalaci. Pokud později přidáte, odeberete nebo změníte moduly, přeinstalujte pro synchronizaci skills (viz Řešení problémů).
Skills vs. spouštěče nabídky agentů
BMad nabízí dva způsoby zahájení práce a slouží k různým účelům.
| Mechanismus | Jak se vyvolává | Co se stane |
|---|---|---|
| Skill | Zadejte název skillu (např. bmad-help) ve vašem IDE |
Přímo načte agenta, spustí workflow nebo provede úkol |
| Spouštěč nabídky agenta | Nejprve načtěte agenta, pak zadejte krátký kód (např. DS) |
Agent interpretuje kód a spustí odpovídající workflow, přičemž zůstává v charakteru |
Spouštěče nabídky agentů vyžadují aktivní relaci agenta. Používejte skills, když víte, který workflow chcete. Používejte spouštěče, když již pracujete s agentem a chcete přepnout úkol bez opuštění konverzace.
Jak se skills generují
Když spustíte npx bmad-method install, instalátor čte manifesty každého vybraného modulu a zapíše jeden skill na agenta, workflow, úkol a nástroj. Každý skill je adresář obsahující soubor SKILL.md, který instruuje AI k načtení odpovídajícího zdrojového souboru a následování jeho instrukcí.
Instalátor používá šablony pro každý typ skillu:
| Typ skillu | Co generovaný soubor dělá |
|---|---|
| Spouštěč agenta | Načte soubor persony agenta, aktivuje jeho nabídku a zůstává v charakteru |
| Workflow skill | Načte konfiguraci workflow a následuje jeho kroky |
| Task skill | Načte samostatný soubor úkolu a následuje jeho instrukce |
| Tool skill | Načte samostatný soubor nástroje a následuje jeho instrukce |
:::note[Opětovné spuštění instalátoru] Pokud přidáte nebo odeberete moduly, spusťte instalátor znovu. Přegeneruje všechny soubory skills tak, aby odpovídaly vašemu aktuálnímu výběru modulů. :::
Kde žijí soubory skills
Instalátor zapisuje soubory skills do adresáře specifického pro IDE uvnitř vašeho projektu. Přesná cesta závisí na IDE, které jste vybrali během instalace.
| IDE / CLI | Adresář skills |
|---|---|
| Claude Code | .claude/skills/ |
| Cursor | .cursor/skills/ |
| Windsurf | .windsurf/skills/ |
| Další IDE | Viz výstup instalátoru pro cílovou cestu |
Každý skill je adresář obsahující soubor SKILL.md. Například instalace Claude Code vypadá takto:
.claude/skills/
├── bmad-help/
│ └── SKILL.md
├── bmad-create-prd/
│ └── SKILL.md
├── bmad-agent-dev/
│ └── SKILL.md
└── ...
Název adresáře určuje název skillu ve vašem IDE. Například adresář bmad-agent-dev/ registruje skill bmad-agent-dev.
Jak objevit vaše skills
Zadejte název skillu ve vašem IDE pro jeho vyvolání. Některé platformy vyžadují povolení skills v nastavení, než se zobrazí.
Spusťte bmad-help pro kontextové poradenství k dalšímu kroku.
:::tip[Rychlé objevování] Generované adresáře skills ve vašem projektu jsou kanonický seznam. Otevřete je v prohlížeči souborů, abyste viděli každý skill s jeho popisem. :::
Kategorie skills
Agentní skills
Agentní skills načítají specializovanou AI personu s definovanou rolí, komunikačním stylem a nabídkou workflow. Po načtení agent zůstává v charakteru a reaguje na spouštěče nabídky.
| Příklad skillu | Agent | Role |
|---|---|---|
bmad-agent-dev |
Amelia (Developer) | Implementuje stories s přísným dodržováním specifikací |
bmad-pm |
John (Product Manager) | Vytváří a validuje PRD |
bmad-architect |
Winston (Architect) | Navrhuje systémovou architekturu |
Viz Agenti pro úplný seznam výchozích agentů a jejich spouštěčů.
Workflow skills
Workflow skills spouštějí strukturovaný, vícekrokový proces bez předchozího načtení persony agenta. Načtou konfiguraci workflow a následují jeho kroky.
| Příklad skillu | Účel |
|---|---|
bmad-product-brief |
Vytvoření product briefu — řízené discovery, když je váš koncept jasný |
bmad-prfaq |
Working Backwards PRFAQ výzva pro zátěžový test vašeho produktového konceptu |
bmad-create-prd |
Vytvoření dokumentu požadavků (PRD) |
bmad-create-architecture |
Návrh systémové architektury |
bmad-create-epics-and-stories |
Vytvoření epiců a stories |
bmad-dev-story |
Implementace story |
bmad-code-review |
Spuštění revize kódu |
bmad-quick-dev |
Sjednocený quick flow — vyjasnění záměru, plán, implementace, revize, prezentace |
Viz Mapa pracovních postupů pro kompletní referenci workflow organizovanou podle fází.
Task a tool skills
Tasks a tools jsou samostatné operace, které nevyžadují kontext agenta nebo workflow.
BMad-Help: Váš inteligentní průvodce
bmad-help je vaše primární rozhraní pro objevení, co dělat dál. Zkoumá váš projekt, rozumí dotazům v přirozeném jazyce a doporučuje další povinný nebo volitelný krok na základě nainstalovaných modulů.
:::note[Příklad]
bmad-help
bmad-help I have a SaaS idea and know all the features. Where do I start?
bmad-help What are my options for UX design?
:::
Další základní tasks a tools
Základní modul zahrnuje 11 vestavěných nástrojů — revize, komprese, brainstorming, správa dokumentů a další. Viz Základní nástroje pro kompletní referenci.
Konvence pojmenování
Všechny skills používají prefix bmad- následovaný popisným názvem (např. bmad-dev, bmad-create-prd, bmad-help). Viz Moduly pro dostupné moduly.
Řešení problémů
Skills se nezobrazují po instalaci. Některé platformy vyžadují explicitní povolení skills v nastavení. Zkontrolujte dokumentaci vašeho IDE nebo se zeptejte AI asistenta, jak skills povolit. Může být také nutné restartovat IDE nebo znovu načíst okno.
Očekávané skills chybí. Instalátor generuje skills pouze pro moduly, které jste vybrali. Spusťte npx bmad-method install znovu a ověřte výběr modulů. Zkontrolujte, že soubory skills existují v očekávaném adresáři.
Skills z odebraného modulu se stále zobrazují. Instalátor automaticky nemaže staré soubory skills. Odstraňte zastaralé adresáře z adresáře skills vašeho IDE, nebo smažte celý adresář skills a přeinstalujte pro čistou sadu.