faq-driven-docs
Installation
SKILL.md
FAQ-driven documentation
Compress knowledge into Q&A so humans and agents can find answers without bloated specs. Pattern proven in production monorepos (e.g. ecsly) and described in FAQ-driven development.
Two files — no duplication
| File | Question type | Audience | Update when |
|---|---|---|---|
| DESIGN_FAQ.md / .mdx | Why — rationale, trade-offs | Maintainers, agents changing architecture | Internals, performance choices, boundaries |
| DX_FAQ.md / .mdx | How — API usage, patterns | Application developers, agents writing client code | Public API, examples, workflows |
Use both when needed; they complement each other. Never copy the same fact into both—link instead.
DESIGN_FAQ rules
- Format:
**Q: …**/**A: …**(2–3 sentences per answer) - Include: decision, trade-off, performance or maintenance context
- Exclude: long tutorials, copy-paste-heavy how-tos (those belong in DX_FAQ)
- Sections: group by theme (Storage, Events, Plugins, …)