# Describe Design

Research a codebase and create architectural documentation describing how features or...

- Repository: https://github.com/posit-dev/skills (551 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add posit-dev/skills --skill describe-design -g -a claude-code -y`
Codex: `npx skills add posit-dev/skills --skill describe-design -g -a codex -y`
Cursor: `npx skills add posit-dev/skills --skill describe-design -g -a cursor -y`
Gemini CLI: `npx skills add posit-dev/skills --skill describe-design -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add posit-dev/skills`

## Description

Research a codebase and create architectural documentation describing how features or systems work. Use when the user asks to: (1) Document how a feature works, (2) Create an architecture overview, (3) Explain code structure for onboarding or knowledge transfer, (4) Research and describe a system's design. Produces markdown documents with Mermaid diagrams and stable code references suitable for humans and AI agents.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Describe Design

Research a codebase and produce an architectural document describing how features or
systems work. The output is a markdown file organized for both human readers and
future AI agents.

## Workflow

### Stage 1: Scope Definition

Understand what to document before exploring:

1. Ask what feature, system, or component to document.
2. Clarify the target audience (developers, AI agents, or both).
3. Confirm the codebase location if not obvious from context.

### Stage 2: Initial Exploration

Explore the codebase broadly to build a mental model. Use lightweight, fast exploration
methods when available (for example, use a fast Explore subagent if your harness supports subagents):

1. Scan directory structure and identify key entry points.
2. Read README, config files, and existing documentation.
3. Identify the main files and modules related to the feature.
4. Build a mental model of codebase organization.

Present a high-level outline to the user:

```
## Proposed Outline

1. [Component A] - Brief description
2. [Component B] - Brief description
3. [Component C] - Brief description

* Have I correctly captured the scope of the research? Reply "yes" to continue.
* Otherwise, please let me know what I've misunderstood.
```

When the user confirms the scope, move on to deep research.

### Stage 3: Deep Research

For each component in the approved outline:

1. Trace code paths from entry points.
2. Identify dependencies and interactions between components.
3. Note configuration options and where they're defined.
4. Find where data is stored or persisted.
5. Build a code reference index (file paths + key function/class names).

Try to rely on the initial code exploration for much of this information. Read
additional files as needed. If the scope changed considerably in Stage 2, you
can engage a second code exploration subagent.

#### When to Stop Exploring

**You're ready to draft when you can:**

The rest: https://github.com/posit-dev/skills/blob/HEAD/posit-dev/describe-design/SKILL.md