Skip to content

tokio-rs/toasty / .agents/skills/design

design

Verified

Always use this skill before authoring or editing a Toasty design document under docs/dev/design/

Authoring Toasty Design Documents

Load this skill before writing or editing a design document in docs/dev/design/.

Format and layout

Always read docs/dev/design/_template.md before writing. It is the authoritative source for section order, section purposes, and the framing the doc should adopt. Copy the template to docs/dev/design/<feature-name>.md and fill it in. Keep the section order; if a section genuinely does not apply, delete it and explain why in one line rather than leaving it empty.

Writing style

Follow the conventions from the prose skill: be fact-focused, direct, and concrete. No buzzwords, no fluff, no dramatic terms.

Be succinct

Readers already know Toasty and Rust. Lead with the problem and the proposal so a maintainer can grasp the important bits quickly. Cut restated background, obvious explanations, and throat-clearing. Length is not a virtue; clarity is.

Rust examples

Rust code blocks in design docs are illustrative. They do not need to compile and are not run through rustdoc or any other test.

Do not add #-prefixed hidden boilerplate — no # use … imports, no # async fn __example(…) { … } wrappers, no # fn main, nothing hidden to satisfy a compiler. Show only the lines that matter to the reader, even if the snippet would not compile on its own.

This overrides the doctest-preamble instruction in _template.md's User-facing API section: that preamble is for the user guide, where examples are tested. Design docs are not.

Framing

A design doc is guide-level, not implementation-level. Write it for the two audiences the template names:

  • Toasty users — Rust developers writing models and queries.
  • Driver implementors — anyone implementing the Driver trait.

Describe what those audiences will see, call, and have to do. Omit internal module layouts and implementation choices that have no observable effect on either audience. The User-facing API section should read like a chapter of the user guide — prose with worked examples, not an API catalog. The examples are still illustrative only (see Rust examples above) — do not add doctest boilerplate to them.

Workflow

Non-trivial features follow the path in CONTRIBUTING.md: open a feature-proposal issue first, then land a roadmap entry in docs/dev/roadmap/ and the design doc in the same PR. The implementation lands as a follow-up PR once the design is accepted.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall