The Describe Design skill is a powerful tool within the OpenClaw framework
that helps developers and teams understand complex codebases by creating
comprehensive architectural documentation. This skill is designed to research
a codebase and produce detailed markdown documents that explain how features
or systems work, complete with Mermaid diagrams and stable code references.
How the Describe Design Skill Works
The skill follows a structured five-stage workflow that ensures thorough and
accurate documentation:
Stage 1: Scope Definition
Before diving into the codebase, the skill first clarifies what needs to be
documented. It asks about the specific feature, system, or component to
document, identifies the target audience (developers, AI agents, or both), and
confirms the codebase location. This initial step ensures the documentation
effort is focused and relevant.
Stage 2: Initial Exploration
The skill then performs a broad exploration of the codebase to build a mental
model. This includes scanning directory structures, reading README files and
configuration files, identifying key entry points, and finding existing
documentation. The goal is to understand the overall organization before
diving deep into specific components.
Stage 3: Deep Research
Once the scope is confirmed, the skill conducts thorough research on each
component. This involves tracing code paths from entry points, identifying
dependencies and interactions between components, noting configuration
options, and finding where data is stored or persisted. The skill builds a
comprehensive code reference index with file paths and key function or class
names.
Stage 4: Document Draft
Using a structured template, the skill generates a draft document that
includes an overview, architecture diagram, component descriptions, data flow
explanations, configuration details, and code references. The draft is
presented to the user for review and iteration based on feedback.
Stage 5: Finalize
The final stage involves confirming the file location before writing the
document. The skill proposes a path based on repository conventions but never
writes the file without explicit user confirmation of the location.
Document Template and Structure
The Describe Design skill uses a comprehensive template that includes:
- An overview section summarizing what the feature or system does
- An architecture diagram using Mermaid flowchart syntax
- Detailed component descriptions with purposes, locations, key functions, and interactions
- Data flow explanations showing how information moves through the system
- Configuration details including file paths and environment variables
- A code references table with stable references that survive refactoring
- A glossary of terms for project-specific definitions
Key Features and Best Practices
The skill emphasizes several important practices:
- Stable references : Using relative paths from the repository root and function/class names rather than line numbers
- Descriptive approach : Explaining what code does and where to find it, rather than copying code directly
- Mermaid diagrams : Creating visual representations of architecture using Mermaid syntax for flowcharts and sequence diagrams
- Two-audience design : Writing clearly for human readers while maintaining consistent structure for AI agents
- Current information : Noting any assumptions about code state or version to ensure accuracy
When to Use the Describe Design Skill
This skill is particularly useful when you need to:
- Document how a feature works for onboarding new team members
- Create an architecture overview for stakeholders
- Explain code structure for knowledge transfer between team members
- Research and describe a system's design for documentation purposes
Benefits of Using This Skill
By using the Describe Design skill, teams can create documentation that serves
both human developers and AI agents, ensuring that architectural knowledge is
preserved and accessible. The skill's structured approach and emphasis on
stable references means the documentation remains useful even as codebases
evolve over time.
The skill helps bridge the gap between complex codebases and the need for
clear, understandable documentation, making it an invaluable tool for software
development teams working on large or complex projects.
Skill can be found at:
design/SKILL.md>
Top comments (0)