Diagram Design
cathrynlavery/diagram-design
Creates branded diagrams, from architecture, flowchart and sequence to charts and maps, as self-contained HTML with inline SVG, with import from draw.io, Mermaid and Excalidraw.
Research a codebase and create architectural documentation describing how features or systems work.
Install Describe Design
$ npx skills add posit-dev/skills --skill describe-design -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install posit-dev/skills describe-design --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/posit-dev/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/posit-dev/describe-design .claude/skills/describe-design && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "describe-design" agent skill from https://github.com/posit-dev/skills/tree/main/posit-dev/describe-design into .claude/skills/describe-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "describe-design", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/posit-dev/skills/tree/main/posit-dev/describe-designType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add posit-dev/skills --skill describe-design -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install posit-dev/skills describe-design --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/posit-dev/skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/posit-dev/describe-design .agents/skills/describe-design && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "describe-design" agent skill from https://github.com/posit-dev/skills/tree/main/posit-dev/describe-design into .agents/skills/describe-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "describe-design", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add posit-dev/skills --skill describe-design -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install posit-dev/skills describe-design --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/posit-dev/skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/posit-dev/describe-design .cursor/skills/describe-design && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "describe-design" agent skill from https://github.com/posit-dev/skills/tree/main/posit-dev/describe-design into .cursor/skills/describe-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "describe-design", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/posit-dev/skills.git --path posit-dev/describe-design--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add posit-dev/skills --skill describe-design -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install posit-dev/skills describe-design --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/posit-dev/skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/posit-dev/describe-design .gemini/skills/describe-design && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "describe-design" agent skill from https://github.com/posit-dev/skills/tree/main/posit-dev/describe-design into .gemini/skills/describe-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "describe-design", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install posit-dev/skills describe-designInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add posit-dev/skills --skill describe-design -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/posit-dev/skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/posit-dev/describe-design .github/skills/describe-design && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "describe-design" agent skill from https://github.com/posit-dev/skills/tree/main/posit-dev/describe-design into .github/skills/describe-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "describe-design", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add posit-dev/skills --skill describe-design -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install posit-dev/skills describe-design --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/posit-dev/skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/posit-dev/describe-design .opencode/skills/describe-design && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "describe-design" agent skill from https://github.com/posit-dev/skills/tree/main/posit-dev/describe-design into .opencode/skills/describe-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "describe-design", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
describe-design- GitHub stars
- 531
- Token cost
- ~1.7k tokens
- SKILL.md length
- 687 words
- Files
- 1
- Skills in repo
- 17
- Repo updated
- First seen
- Licence
- MIT
At a glance
Research a codebase and create architectural documentation describing how features or systems work.
- Works in 5 steps: Scope Definition → Initial Exploration → Deep Research → …
- The user asks to:
- SKILL.md covers Workflow, Document Template, Code Reference Conventions and Mermaid Diagrams, plus 1 more section
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Describe Design is an agent skill from posit-dev/skills. 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.
Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Technical documentation. The repository describes itself as: A collection of Claude Skills from Posit. The licence is MIT.
When your agent uses it
- The user asks to:
- Document how a feature works
- Create an architecture overview
- Explain code structure for onboarding
Example prompts
- “/describe-design”
Workflow steps
5 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit e20b71b. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are mermaid and markdown).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Describe Design loads about 1.7k tokens when it runs. Until then it costs about 109 tokens; SKILL.md has 687 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from posit-dev/skills at commit e20b71b, republished under its MIT licence (© posit-dev). 687 words, ~1,744 tokens.
Download SKILL.mdSave it as
.claude/skills/describe-design/SKILL.md (or your agent's skills folder).- name
- describe-design
- 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.
- metadata.author
- Garrick Aden-Buie (@gadenbuie)
- metadata.version
- 1.1
- license
- MIT
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:
- Ask what feature, system, or component to document.
- Clarify the target audience (developers, AI agents, or both).
- 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):
- Scan directory structure and identify key entry points.
- Read README, config files, and existing documentation.
- Identify the main files and modules related to the feature.
- 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:
- Trace code paths from entry points.
- Identify dependencies and interactions between components.
- Note configuration options and where they're defined.
- Find where data is stored or persisted.
- 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:
- Trace the happy path — Follow a typical request/action from entry point to completion without gaps.
- Name the boundaries — Clearly state what's in scope and what's external.
- Draw the diagram — Sketch the architecture without placeholder boxes.
- Answer "what talks to what?" — For each component, you know its inputs and outputs.
Signs you're not done:
- Uncertainty: "I think this connects to..." or "probably calls..."
- Unresolved references: Found imports/calls to modules you haven't examined.
- Missing edges: Can't explain how data gets from component A to B.
Signs you've gone too far:
- Reading every file in a directory instead of representative samples.
- Tracing into external libraries or framework internals.
- Exploring implementation details that don't affect architecture.
Stage 4: Document Draft
Generate the document following the template below. Present the draft to the user for review and iterate based on feedback. If available, use the AskUserQuestion tool to request user input on key decisions.
Show full SKILL.md (284 more words)Show less
Stage 5: Finalize
- Confirm the file location before writing. You may propose a path based on repository
conventions (e.g.,
docs/architecture/,ARCHITECTURE.md), but NEVER write the file without explicit user confirmation of the location. If the user provided a path upfront, that counts as confirmation. - Write the final document to the confirmed location.
Document Template
The following template provides a starting point. Adapt it to fit the feature being documented — omit sections that don't apply, add sections for unique aspects, and adjust the structure to best serve the target audience.
# [Feature/System Name] Architecture
## Overview
[1-2 paragraph summary of what this feature/system does and why it exists]
## Architecture Diagram
```mermaid
flowchart TD
A[Entry Point] --> B[Component]
B --> C[Data Store]
```
## Components
### [Component Name]
**Purpose**: [What it does]
**Location**: `path/to/file.ext`
**Key Functions**:
- `functionName()` - Brief description
- `anotherFunction()` - Brief description
**Interactions**:
- Receives input from: [Component]
- Sends output to: [Component]
## Data Flow
[Description of how data moves through the system, from input to output]
## Configuration
[How features are enabled, disabled, or configured. Include file paths and
environment variables.]
## Code References
| Component | File | Key Symbols |
|-----------|------|-------------|
| Auth | `src/auth/index.ts` | `authenticate()`, `AuthConfig` |
| Cache | `src/cache/redis.ts` | `CacheManager`, `invalidate()` |
## Glossary
| Term | Definition |
|------|------------|
| [Term] | [Project-specific definition] |Code Reference Conventions
Use stable references that survive refactoring:
- Paths: Use relative paths from repository root (
src/auth/login.ts) - Symbols: Reference function and class names, not line numbers
- Format:
path/to/file.extwith key symbols listed separately - Anchors: Use search patterns when helpful (
handleAuth function in auth/)
Avoid:
- Copying code: Never paste code into the document. Code goes stale immediately; the document should be a guide that points readers to the source. Describe what code does, then reference where to find it.
- Line numbers: They change with every edit.
- Absolute paths: Use repository-relative paths only.
Mermaid Diagrams
Use Mermaid for architecture visualizations:
Flowcharts for component relationships:
flowchart TD
A[Client] --> B[API Gateway]
B --> C[Service]
C --> D[(Database)]Sequence diagrams for request flows:
sequenceDiagram
Client->>API: Request
API->>Service: Process
Service-->>API: Response
API-->>Client: ResultKeep diagrams focused on the specific feature being documented. Avoid overcrowding with unrelated components.
Writing Guidelines
- Describe, never copy: Explain what code does and where to find it. Readers who need implementation details will read the actual source — which is always current.
- Structure for scanning: Use headers, tables, and lists for quick navigation.
- Be specific: Include actual file paths, function names, and config keys.
- Serve two audiences: Write clearly for humans; use consistent structure for AI.
- Stay current: Note any assumptions about code state or version.
© posit-dev, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in posit-dev/describe-design of posit-dev/skills.
Open the folder on GitHubat commit e20b71b
Compare with similar skills
Describe Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Describe Design this skillposit-dev/skills | 531 | — | ~1.7k | Automated safety check: Pass | MIT | |
| Diagram Designcathrynlavery/diagram-design | 45k | 1 repos | ~7.5k | Automated safety check: Pass | MIT | |
| Simple Englishmoeru-ai/airi | 50k | 2 repos | ~4.6k | Automated safety check: Pass | MIT | |
| Get API Docs with chubandrewyng/context-hub | 14k | 2 repos | ~775 | Automated safety check: Pass | MIT | |
| Doc SyncJetBrains/ideavim | 10k | 2 repos | ~2.6k | Automated safety check: Pass | MIT | |
| Mailspring App ScreenshotsFoundry376/Mailspring | 18k | — | ~1.5k | Automated safety check: Pass | GPL-3.0 |
Similar skills
Simple English
moeru-ai/airi
Write or rewrite technical text with the rules of ASD-STE100 Simplified Technical English so it is clear, unambiguous, and free of AI slop.
Get API Docs with chub
andrewyng/context-hub
Fetches current documentation for third-party APIs and SDKs with the chub CLI before the agent writes code against them, instead of relying on remembered API shapes.
- Official
Doc Sync
JetBrains/ideavim
Keeps IdeaVim documentation in sync with code changes. An agent skill from JetBrains/ideavim.
Mailspring App Screenshots
Foundry376/Mailspring
Captures screenshots of the running Mailspring dev app for docs, PRs or visual checks by launching it with a debugging port, driving the UI and clipping to an element.
Draw.io Diagram Studio
Agents365-ai/drawio-skill
Creates and edits editable draw.io diagrams from descriptions, code, infrastructure files, SQL and API schemas, with sync, review, test and export tools.
More from posit-dev/skills
All 17 skills in this repoR CLI App
posit-dev/skills
Build command-line apps in R using the Rapp package. An agent skill from posit-dev/skills.
R Lifecycle
posit-dev/skills
Guidance for managing R package lifecycle according to tidyverse principles using the lifecycle package.
PR Create
posit-dev/skills
Creates a pull request from current changes, monitors GitHub CI, and debugs any failures until CI passes.
Shiny Bslib
posit-dev/skills
Build modern Shiny dashboards and applications using bslib (Bootstrap 5).
Shiny Bslib Theming
posit-dev/skills
Advanced theming for Shiny apps using bslib and Bootstrap 5.
Critical Code Reviewer
posit-dev/skills
Rigorously review code or pull requests for correctness, security, accessibility, maintainability, tests, and edge cases.
Related
Categories
Questions about Describe Design
What does Describe Design do?
Research a codebase and create architectural documentation describing how features or systems work. Describe Design is an agent skill from posit-dev/skills. Research a codebase and create architectural documentation describing how features or systems work.
When should I use Describe Design?
Describe Design fits situations like: the user asks to:; document how a feature works; create an architecture overview; explain code structure for onboarding.
How do I install Describe Design in Claude Code?
Run `npx skills add posit-dev/skills --skill describe-design -a claude-code`. Or copy the skill folder (posit-dev/describe-design in posit-dev/skills) into .claude/skills/describe-design in your project. Claude Code loads it when a task matches its description.
How do I install Describe Design in Codex?
Run `npx skills add posit-dev/skills --skill describe-design -a codex`. Or copy the skill folder (posit-dev/describe-design in posit-dev/skills) into .agents/skills/describe-design in your project. Codex loads it when a task matches its description.
Can I use Describe Design in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add posit-dev/skills --skill describe-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/describe-design, .gemini/skills/describe-design, .github/skills/describe-design and .opencode/skills/describe-design in your project.
What does Describe Design need to run?
SKILL.md names no scripts, command-line tools or credentials: Describe Design is instructions for the agent only.
Does Describe Design access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Describe Design safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Describe Design use?
Describe Design is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Describe Design use?
About 1.7k tokens (SKILL.md is roughly 7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Describe Design?
Skills that share tags, products or a category with Describe Design: Diagram Design (cathrynlavery/diagram-design, 45k stars), Simple English (moeru-ai/airi, 50k stars), Get API Docs with chub (andrewyng/context-hub, 14k stars) and Doc Sync (JetBrains/ideavim, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Describe Design?
posit-dev (a GitHub organization) maintains it in posit-dev/skills, which has 531 GitHub stars. The repository holds 17 skills in this directory. The repository was last updated on October 7, 2026.
Source: posit-dev/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.