software-design
/software-design
Plan a feature or substantial refactor, or assess a design's interfaces, state ownership, module boundaries, abstractions, and error handling. Use when implementation needs decisions that are still open, when the user asks how to approach or structure a change, how an internal module should expose its behavior, or whether an abstraction or dependency earns its place. Not for routine edits, executing an approved plan, or a question only about public API usage, file placement, or naming.
- Author
- gustavovalverde ↗
- Repository
- skills ↗
- Licence
- MIT
- Last repository change
- 19.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Plan a feature or substantial refactor, or assess a design's interfaces, state ownership, module boundaries, abstractions, and error handling. Use when implementation needs decisions that are still open, when the user asks how to approach or structure a change, how an internal module should expose its behavior, or whether an abstraction or dependency earns its place. Not for routine edits, executing an approved plan, or a question only about public API usage, file placement, or naming.
Original author description
Plan a feature or substantial refactor, or assess a design's interfaces, state ownership, module boundaries, abstractions, and error handling. Use when implementation needs decisions that are still open, when the user asks how to approach or structure a change, how an internal module should expose its behavior, or whether an abstraction or dependency earns its place. Not for routine edits, executing an approved plan, or a question only about public API usage, file placement, or naming.
How it works
- Approach
- Gotchas
- Finish
- References
SKILL.md preview
--- name: software-design description: Plan a feature or substantial refactor, or assess a design's interfaces, state ownership, module boundaries, abstractions, and error handling. Use when implementation needs decisions that are still open, when the user asks how to approach or structure a change, how an internal module should expose its behavior, or whether an abstraction or dependency earns its place. Not for routine edits, executing an approved plan, or a question only about public API usage, file placement, or naming. license: MIT --- # Design software Work from a representative user task toward the implementation, and compare the simplest viable design with the smallest useful alternative before changing structure. ## Approach Start with the requested outcome, constraints, and decisions still open. Inspect relevant code, callers, and tests before judging an existing design. For new software, separate supplied requirements from assumptions. When executing an approved plan, check changed assumptions and proceed; reopen only decisions that new evidence undermines. Establish the domain concepts and the observable success, failure, and unknown outcomes. Sketch the common usage, then trace state ownership, invariants, and lifecycle or transaction boundaries. Iterate between usage and ownership before settling file placement and names. Keep user-significant policy explicit while hiding coordination callers should not need to manage. Compare the current or simplest design with the smallest useful alternative, including leaving the structure unchanged. Ask what callers must understand, where maintainers must navigate, and which changes require coordination. These are qualitative questions, not a complexity score. Preserve security, resource ownership, transaction, and compatibility boundaries when simplifying. This workflow is complete on its own. When one decision needs more depth, use the focused skill for it when available, and pass along what is already established: - `public-api-design` for developer-facing usage and compatibility, with the representative task and usage sketch. - `codebase-structure` for placement and moves, with the settled ownership. - `identifier-naming` for disputed vocabulary or renames, with the domain concepts. - `docs-writing` when the user asks to record the decision as an ADR or proposal, with the decision, alternatives, and evidence. ## Gotchas - A single implementation, long function, conditional, or unfamiliar convention is not evidence of a defect. - One implementation can justify an interface when it isolates a dependency or makes behavior testable. - Similar code can encode independent policies. Sharing it can couple changes that should stay separate. - Catching every storage error and returning `null` turns an outage into "not found". - Combining modules cannot make a database write and an email send commit atomically. ## Finish Make the result proportional to the task: the decision, supporting evidence, costs, and unresolved questions, with demonstrated failures separated from tradeoffs and preferences. Identify the smallest useful implementation slice and the checks that would establish its behavior and contract. An assessment can end there. When implementation is requested, preserve behavior outside the agreed change and verify affected consumers and failure paths. ## References - [Principles and tradeoffs](references/principles.md) when deciding whether an abstraction, dependency, or module boundary helps. - [Decision examples](references/examples.md) for concrete comparisons and scoping a first implementation slice.
Files in this package (6)
- LICENSE 1 KB
- SKILL.md 4 KB
- agents/openai.yaml 1 KB
- references/examples.md 3 KB
- references/principles.md 4 KB
- references/sources.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · gustavovalverde/skills | 100 | MIT |
| usetemi/skills | 90 | MIT |
Database snapshot: 13.11.2026 · package version c71d58612ef6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90uds-architecture
Use when choosing or reviewing application structure, module boundaries, dependency direction, logic ownership, or significant architectural decisions. - 100software-architecture
Design, evolve, and review software architecture, from small tools and libraries to multi-service systems. Use for module boundaries, domain models, public contracts, data ownership, quality trade-offs, architectural refactoring, and behavior-preserving simplification. - 90bec-architecture-design
Use when Backend module/service boundaries, data ownership, dependency direction, consistency requirements or architecture tradeoffs need design or review. - 84design
Resolve design decisions (types, contracts, package topology, module boundaries) in discussion rounds before /planning:plan, as design artifacts. Use when: 'design this', 'type modeling', 'figure out the abstractions', 'model this domain', 'what should the types look like', 'how… - 100codebase-structure
Decide where code belongs, including file and module placement, splitting or merging modules, flattening or nesting directories, and moving files across boundaries. Use when the user asks where something should go, whether to split or merge files, how to organize a folder or… - 90cc-go-project-standard
Use when Go module/workspace organization, package ownership, error and context conventions, dependency boundaries or engineering validation need design or review.