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/

FileKindSize
SKILL.mdskill md2.7 KB
---
name: design
description: 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/`](../../../docs/dev/design/).

## Format and layout

**Always read [`docs/dev/design/_template.md`](../../../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`](../prose/SKILL.md) 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`](../../../CONTRIBUTING.md): open a feature-proposal
issue first, then land a roadmap entry in
[`docs/dev/roadmap/`](../../../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: 323kUpdated 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