Describe Design

What it does

This skill analyzes a codebase and generates architectural documentation describing how features or systems work. It produces a markdown file suitable for both human readers and future AI agents, following a structured workflow that includes scope definition, exploration, deep research, draft generation, and finalization. The process involves building a mental model of the codebase and presenting an outline for user confirmation before proceeding with detailed analysis.

When to use it

• Documenting complex features or systems within a codebase.
• Creating architectural overviews for new developers joining a project.
• Generating documentation for AI agents that need to understand system behavior.
• Clarifying the interactions between different components of a software application.
• Building a reference guide for troubleshooting and maintenance purposes.

Key capabilities

• Scope Definition: Clarifies the feature, system, or component to be documented, along with the target audience.
• Code Exploration: Scans directory structures, README files, configuration files, and key modules within a codebase.
• Outline Generation: Creates a proposed outline of components for user approval before deep research begins.
• Deep Research: Traces code paths, identifies dependencies, notes configuration options, and builds a code reference index.
• Architecture Diagramming: Visually represents the system architecture.
• Markdown Document Generation: Produces a structured markdown document describing the analyzed feature or system.

Example prompts

• "Describe the functionality of the user authentication module in this repository."
• "Create architectural documentation for the payment processing service, targeting developers."
• "Document how the image resizing component works within the codebase."

Tips & gotchas

• The skill relies on initial code exploration methods like Haiku Explore (available in Claude Code) to efficiently build a mental model.
• User confirmation is crucial at each stage; respond "yes" to confirm the proposed outline and scope.
• Avoid exploring external libraries or framework internals, as this can lead to unnecessary complexity.