Understanding the Describe Design Skill in OpenClaw: A Comprehensive Guide

Source: Dev.to

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 clarifies what needs to be documented. It asks about the specific feature, system, or component, identifies the target audience (developers, AI agents, or both), and confirms the codebase location. This initial step keeps the documentation effort focused and relevant.

Stage 2: Initial Exploration

The skill performs a broad exploration of the codebase to build a mental model. This includes scanning directory structures, reading README and configuration files, identifying key entry points, and locating 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. It traces code paths from entry points, identifies dependencies and interactions, notes configuration options, and finds where data is stored or persisted. A comprehensive code reference index with file paths and key function or class names is built.

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 confirms 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:

• Overview – summarizing what the feature or system does
• Architecture diagram – using Mermaid flowchart syntax
• Component descriptions – purpose, location, key functions, and interactions
• Data flow explanations – showing how information moves through the system
• Configuration details – file paths and environment variables
• Code references table – stable references that survive refactoring
• Glossary – project‑specific term definitions

Key Features and Best Practices

• Stable references – use relative paths from the repository root and function/class names rather than line numbers.
• Descriptive approach – explain what code does and where to find it, rather than copying code directly.
• Mermaid diagrams – create visual representations of architecture using Mermaid syntax for flowcharts and sequence diagrams.
• Two‑audience design – write clearly for human readers while maintaining a consistent structure for AI agents.
• Current information – note 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 architectural knowledge is preserved and accessible. The structured approach and emphasis on stable references keep the documentation 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 location: design/SKILL.md