faq-driven-docs
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 | Why — rationale, trade-offs | Maintainers, agents changing architecture | Internals, performance choices, boundaries |
| DX_FAQ.md | 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, …)
More from arenukvern/skill_steward
adr-records
Writes and maintains ADRs (MADR, Nygard, Y-Statement) and runs decision checkpoints before/during work—trigger matrix, option briefs, proposed ADRs. Use when creating or updating ADRs, facing a design fork, trade-off, boundary change, or when the user asks for key design decisions before implementing.
1create-skill
Scaffold a new Agent Skill in this marketplace repo with valid SKILL.md, directory layout, and registry entries. Use when adding a skill, creating SKILL.md, or contributing to skill_steward.
1skill-source-citations
Requires durable citations when authoring or researching Agent Skills—maintain references/sources.md per skill, link external research, and record provenance in PRs. Use when creating skills, updating SKILL.md, doing web research for skills, or auditing missing sources.
1skill-spec-review
Audit SKILL.md and skill directories for Agent Skills spec, Cursor extensions, and npx skills compatibility. Use when reviewing a skill, validating frontmatter, or checking marketplace readiness.
1concept-doc-store
Bootstraps and maintains a vectorless, layered documentation store for concepts, architecture, and decisions—without duplicating how code works. Use when organizing repo docs, writing ADRs, north-star charters, agent playbooks, or product-style doc lattices.
1multi-agent-handoff
Plan and document handoffs between specialized AI agents (foreman, workers, reviewers). Use for multi-agent workflows, subagent delegation, baton passes, or guild-style agent coordination.
1