describe-design
Skill2 starsChanged 6 months agoMITView on GitHub
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.
2 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- BrightGold70/skillsedited, first seen Nov 8, 2026
- keez97/claude-architecture-skillstheir own version, first seen Mar 29, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- BrightGold70/skills★ 199% same
Wrote their own version · 1
- keez97/claude-architecture-skills★ 8same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- alt-textSkill
- brand-ymlSkill
- cliSkill
- cran-extrachecksSkill
- create-release-checklistSkill
- critical-code-reviewerSkill
- ggsqlSkill
- implementSkill
- maintainer-declineSkill
- miraiSkill
- pr-createSkill
- pr-threads-addressSkill
- pr-threads-resolveSkill
- quarto-authoringSkill
- r-cli-appSkill
- release-postSkill
- review-testingSkill
- r-package-developmentSkill
- shiny-bslibSkill
- shiny-bslib-themingSkill
- testing-r-packagesSkill
- working-onSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 11 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Ask what feature, system, or component to document.
- Distinctive: line 32
Read README, config files, and existing documentation.
- Distinctive: line 49
When the user confirms the scope, move on to deep research.
- Distinctive: line 99
Write the final document to the confirmed location.
- Distinctive: line 163
Use stable references that survive refactoring:
- Very specific: line 165
Paths: Use relative paths from repository root (src/auth/login.ts)
- Very specific: line 168
Anchors: Use search patterns when helpful (handleAuth function in auth/)
- Distinctive: line 172
Copying code: Never paste code into the document.
- Distinctive: line 176
Absolute paths: Use repository-relative paths only.
- Distinctive: line 180
Use Mermaid for architecture visualizations:
- Distinctive: line 199
Keep diagrams focused on the specific feature being documented.
- Distinctive: line 206
Structure for scanning: Use headers, tables, and lists for quick navigation.
- Distinctive: line 208
Serve two audiences: Write clearly for humans; use consistent structure for AI.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 (in Claude Code, for example, use a Haiku Explore subagent):
- 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.
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

