Claude Code explanation-docs for design trade-offs

Explain the problem, mechanism, design rationale, and trade-offs for readers seeking conceptual understanding.

Install in Claude Code

Open Claude Code with existing design records or confirmed system behavior. Have the constraints, alternatives, and reader questions that support the explanation.

Review `.claude/skills/explanation-docs/SKILL.md` and its requirements at the pinned GitHub commit.
Create `.claude/skills/explanation-docs/` in your project and save the reviewed file as `.claude/skills/explanation-docs/SKILL.md`.
Start Claude Code from that project's root, then select `/explanation-docs` in the slash menu.

Example task

Document docs-38 explains a dedicated cache for event images. The facts are {updates: 'weekly', goal: 'fewer repeated downloads'}. The cache may delay a just-updated image.

What to check

Explain {benefit: 'fewer repeated downloads', tradeoff: 'temporary stale images'}. Discuss invalidation as a mechanism and link operational steps separately.

Original SKILL.md on GitHub · Updated 2026-11-14

Frequently asked question

Does a conceptual explanation need clickable instructions?

Focus on why the system works and how its parts relate. Link to an action guide when the reader needs operational steps.