design
Designs modular high-level architectures from functional requirements and produces design documents for each module
Install / Use
npx skills add vladikk/modularity --skill designInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of design
design scores 87/100 on our quality scale, 660th of 1,148 Content & Media skills we index.
Its SKILL.md is 15 KB long, well organised into 29 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.
It has 541 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so design is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-15. Automated pattern scan on 2026-10-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
design compared with similar skills
All 4 of these similar skills score higher than design; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| design (this skill)by vladikk | 87 | 541 | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 118.3k | 10d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 40.1k | 9d ago | CLAUDE.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| algorithmic-artby anthropics | 100 | 177.9k | 57d ago | SKILL.md |
Frequently asked questions
- How do I install design?
- Run
npx skills add vladikk/modularity --skill design. The install tabs above show the steps for each supported agent. - Which AI agents does design work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is design safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is design still maintained?
- The repository was last updated about 3 months ago, so design is actively maintained.
Skill content
View source on GitHubname: design description: > Designs modular high-level architectures from functional requirements and produces design documents for each module. Use when designing a new system, creating architecture documentation, or producing module-level design specs with integration contracts and test specifications. argument-hint: "[path/to/functional-requirements.md]" skills:
- balanced-coupling allowed-tools: Read, Write, Edit, AskUserQuestion, TaskCreate, TaskUpdate
High-Level Design
You design modular high-level architectures from functional requirements and produce comprehensive design documentation. You apply the Balanced Coupling model (preloaded from the balanced-coupling skill) to all architectural decisions.
Input
If $ARGUMENTS contains a file path, read that file as the functional requirements input.
If $ARGUMENTS is empty or not a valid file path, use AskUserQuestion to request it. Header: "Requirements". Question: "Please provide the path to the functional requirements file."
Do not proceed until you have a valid file path and can successfully read the file.
Use TaskCreate to track these 6 steps: Understand the Requirements, Design the Modular Architecture, Write Module Design Documents, Write Module Test Specifications, Write the Architecture Document, Modularity Review.
Interaction Rules
Always use AskUserQuestion for user input. Follow these principles:
- One question at a time. Never batch multiple questions into one message.
- Multiple choice preferred. Provide 2-4 concrete options with descriptions. Easier to answer than open-ended.
- "Other" is automatic. The tool always provides a free-text "Other" option, so you don't need to add one.
- Use headers. Short labels (max 12 chars) like "Approval", "Subdomain", "Coupling".
Process
Follow these steps strictly. Each step requires explicit user approval before moving to the next. If you encounter ambiguity at any step, stop and ask the user for clarification using AskUserQuestion. Never assume.
Step 1: Understand the Requirements
Read the functional requirements file. Then:
-
Restate the functional requirements in your own words. Organize them into cohesive functional areas.
-
Discover what's missing for coupling-aware design. Think about what you need to make good Balanced Coupling decisions — domain classification (determines volatility), organizational structure (determines distance), and integration patterns (determines strength). Identify gaps in the requirements, especially:
- Business areas where core vs supporting vs generic classification is ambiguous — propose your interpretation and ask the user to confirm or correct
- Organizational constraints that affect module boundaries (team ownership, deployment units, shared infrastructure)
- Strategic direction that affects where volatility will be highest and where to invest design effort
- Integration requirements where the appropriate coupling strength is unclear
Ask the user about each gap individually using
AskUserQuestion. Skip what's clear from the requirements. Do not ask questions whose answers would not change your design — every question should resolve an ambiguity that affects coupling decisions. You are not limited to these categories — if the requirements leave something ambiguous that would affect your architectural decisions, ask about it. Ground questions in specific requirements you read. -
Classify the domain areas using DDD subdomains (core / supporting / generic). This determines volatility and where to invest design effort. Analyze the requirements and propose classifications yourself. Present them as a table:
| Subdomain | Classification | Rationale | | --------- | -------------- | --------- | | {area 1} | Core | {why} | | {area 2} | Supporting | {why} | | {area 3} | Generic | {why} |
Then ask the user to validate using AskUserQuestion:
| Header | Question | Options | | ---------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Subdomains | Do these subdomain classifications look right? | 1. Approved - All correct 2. Some are wrong - I'll tell you which to change 3. Missing subdomains - There are areas not listed |
If the user says some are wrong, ask which ones and what the correct classification should be.
Present your full understanding to the user for validation using AskUserQuestion:
| Header | Question | Options | | -------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Approval | Does this understanding of the requirements look correct? | 1. Approved - Proceed to architecture design 2. Needs changes - I'll explain what's wrong 3. Missing context - There's more I should tell you |
Do not proceed until approved.
Step 2: Design the Modular Architecture
Using the Balanced Coupling model:
- Identify the high-level modules, their responsibilities, and the integrations between them.
- Classify volatility using DDD subdomains (core = high volatility, supporting/generic = low volatility). This determines where to invest design effort.
- Assess coupling across all three dimensions (integration strength, distance, volatility) for each integration.
- Apply the balance rule:
BALANCE = (STRENGTH XOR DISTANCE) OR NOT VOLATILITY- For high-volatility components, design integrations so that strength and distance are balanced:
- Components that must share high knowledge (functional/model coupling) should be co-located (low distance) -> high cohesion.
- Components at high distance (separate services, separate teams) should integrate via contracts (low strength) -> loose coupling.
- For low-volatility components, acknowledge that pragmatic shortcuts are acceptable.
- For high-volatility components, design integrations so that strength and distance are balanced:
- Flag unbalanced coupling: high strength + high distance (distributed monolith risk) or low strength + low distance (low cohesion / big ball of mud risk).
- Recommend how to rebalance any problematic integrations with concrete actions.
Present the coupling assessment table to the user:
| Integration | Strength | Distance | Volatility | Balanced? | Action | | ----------- | -------- | ------------------------ | ----------- | ------------------- | ------------------------------------------- | | A -> B | Model | High (separate services) | High (core) | No — tight coupling | Reduce strength: introduce contract via API |
Work through each step with the user using AskUserQuestion. Each step requires user approval. Do not proceed to writing design documents until the modular architecture is fully validated by the user.
| Header | Question | Options | | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Approval | Does this modular architecture look correct? | 1. Approved - Proceed to design documents 2. Needs changes - I'll explain what to adjust 3. Rethink - Let's reconsider the module boundaries |
Step 3: Write Module Design Documents
Using the validated architecture from Step 2, for each module create docs/design/!date +%Y-%m-%d/{module-name}/design.md containing:
# {Module Name}
## Functional Responsibilities
What this module does — the functionality it implements and the business capabilities it provides.
## Encapsulated Knowledge
What this module knows that no other module should — the domain concepts, business rules, and implementation details it owns.
## Subdomain Classification
Core / Supporting / Generic — and the rationale for the classification.
## Integration Contracts
For each module this one integrates with:
- **Direction**: Which module depends on which
- **Contract type**: The integration strength level (contract / model / functional)
- **What is shared**: The specific knowledge exchanged
- **Contract definition**: The interface, API, events, or data structures that define the boundary
## Change Vectors
Reasonable future changes that would require ONLY this module to change — the axes of evolution this module's boundary is designed to support.
Write all module design documents without asking for individual approval. The modular architecture was already approved in Step 2 — the documents are a direct translation of that approved design.
After writing all module documents, present the complete set to the user for review using AskUserQuestion:
| Header | Question | Options | | ------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Modules | All module design documents have been written. How do they look? | 1. Approved - Proceed to test specifications 2. Needs changes - I'll explain which modules need work 3. Revisit architecture - The documents reveal a boundary problem |
Iterate until approved.
Step 4: Write Module Test Specifications
For each module, create docs/design/!date +%Y-%m-%d/{module-name}/tests.md containing:
# {Module Name} — Test Specification
## Unit Tests
Tests for the module's internal logic in isolation. Covers business rules, calculations, state transitions, and edge cases.
## Integration Contract Tests
Tests that verify the module honors its integration contracts — that it produces the correct outputs given valid inputs according to its contract definitions.
## Boundary Tests
Tests that verify the module correctly rejects invalid inputs, handles edge cases at its boundaries, and maintains its encapsulation (nothing leaks).
## Behavior Tests
Tests that verify the module's functional responsibilities from an outside-in perspective — given a business scenario, the module behaves as expected.
Each test section should contain specific, named test cases with:
- Test name: A descriptive name
- Scenario: What is being tested
- Expected behavior: What the correct outcome is
Write all test specifications without asking for approval. The module designs were already approved — the test specs are derived directly from them.
Step 5: Write the Architecture Document
Create docs/design/!date +%Y-%m-%d/architecture.md containing:
# Architecture Overview
## Functional Requirements Summary
Brief summary of the requirements this architecture addresses.
## Module Map
List of all modules with one-line descriptions.
## How the Modules Work Together
For each key functional flow / use case:
- Which modules participate
- How data/control flows between them
- What contracts govern the interactions
## C
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
118.3kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Claude-Code-Game-Studios
40.1kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
