Skip to content
Skills Library
Programming · Learning & explanation

engineering-principles

/engineering-principles

Use when writing, designing, refactoring or extending code: where logic belongs, how much abstraction is enough, module and interface structure, error handling, validation at boundaries, naming, what a test should prove. Triggers on "how should I structure this", "is this too complex", "should I abstract this". Not for checking a finished diff before a PR (use reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles, testing-principles, domain-driven-design). Not for choosing or implementing a named pattern (use design-patterns). Not for system-level layering, CQRS, sagas, event-d

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when writing, designing, refactoring or extending code: where logic belongs, how much abstraction is enough, module and interface structure, error handling, validation at boundaries, naming, what a test should prove. Triggers on "how should I structure this", "is this too complex", "should I abstract this". Not for checking a finished diff before a PR (use reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles, testing-principles, domain-driven-design). Not for choosing or implementing a named pattern (use design-patterns). Not for system-level layering, CQRS, sagas, event-d

Triggers from the description

how should I structure thisis this too complexshould I abstract this
Original author description

Use when writing, designing, refactoring or extending code: where logic belongs, how much abstraction is enough, module and interface structure, error handling, validation at boundaries, naming, what a test should prove. Triggers on "how should I structure this", "is this too complex", "should I abstract this". Not for checking a finished diff before a PR (use reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles, testing-principles, domain-driven-design). Not for choosing or implementing a named pattern (use design-patterns). Not for system-level layering, CQRS, sagas, event-d

How it works

  1. What to load
  2. Related skills
Original SKILL.md headings · 36 lines, 410 words
SKILL.md preview
---
name: engineering-principles
description: >-
  Use when writing, designing, refactoring or extending code: where logic
  belongs, how much abstraction is enough, module and interface structure,
  error handling, validation at boundaries, naming, what a test should prove.
  Triggers on "how should I structure this", "is this too complex", "should I
  abstract this". Not for checking a finished diff before a PR (use
  reviewing-code). Not for deep SOLID, TDD or DDD (use solid-principles,
  testing-principles, domain-driven-design). Not for choosing or
  implementing a named pattern (use design-patterns). Not for system-level
  layering, CQRS, sagas, event-driven design or service splits (use code-architectures).
metadata:
  last_updated: "2026-11-11"
---

# Engineering Principles

A small set of principles covers most of what makes code good. Apply them while you write, in this order, because an early mistake is expensive to fix later:

1. **Scope.** Do what was asked and nothing more. KISS, YAGNI, DRY with the Rule of Three, Gall's Law (grow a working simple system, don't design a complex one). Delete before you add.
2. **Design.** Separate concerns, give each unit one reason to change, depend on abstractions at real seams, prefer composition, tell objects what to do instead of pulling their state apart (Law of Demeter, Tell Don't Ask), keep queries and commands separate.
3. **Correctness.** Parse at the boundary and trust the types inside, fail fast on every path, make illegal states unrepresentable, grant the least privilege, remember that any observable behavior becomes a contract (Hyrum's Law).
4. **Readability and tests.** Least astonishment, explicit over implicit, the idiom the language expects, and a test that fails when the behavior breaks.

Get scope and design right before polishing lines. Hand anything a rule can state (formatting, imports, types) to a tool, not to judgment.

## What to load

Open only what the task needs.

| You are... | Read |
|---|---|
| Deciding what to build, or how much | [principles.md](references/principles.md), "1. Simplicity and scope" |
| Structuring modules, classes, interfaces, dependencies | [principles.md](references/principles.md), "2. Design and structure" |
| Handling input, errors, concurrency, data models, permissions, performance | [principles.md](references/principles.md), "3. Correctness and safety" |
| Naming, clarity, idioms, writing tests | [principles.md](references/principles.md), "4. Readability and tests" |
| Writing Python, TypeScript or JavaScript, Rust, shell or SQL | [language-notes/index.md](references/language-notes/index.md), then the one file for that language |

The one-paragraph summaries at the top of `principles.md` ("Principles") are enough for a quick decision. Read the detailed section when the summary doesn't settle it.

## Related skills

- `solid-principles`: the full SRP/OCP/LSP/ISP/DIP treatment with bad-to-good examples.
- `testing-principles`: what a good test is, plus the red-green-refactor discipline (its `test-driven-development` reference) and test doubles.
- `domain-driven-design`: aggregates, value objects and bounded contexts.
- `code-architectures`: layering, CQRS, event sourcing, event-driven design and service boundaries.
- `senior-engineering-best-practices`: verifying docs before a workaround, root-cause discipline, blast radius, dependency judgment.
- `reviewing-code`: the process for checking a finished diff against these principles, with per-change-type playbooks (endpoints, migrations, auth, Dockerfiles and so on).
- `design-patterns`: the catalog of named patterns, with a reference per pattern. Use it once you have decided an abstraction is warranted.
Files in this package (8)
  • SKILL.md 4 KB
  • references/principles.md 45 KB
  • references/language-notes/index.md 3 KB
  • references/language-notes/python.md 7 KB
  • references/language-notes/rust.md 8 KB
  • references/language-notes/shell.md 4 KB
  • references/language-notes/sql.md 3 KB
  • references/language-notes/typescript.md 8 KB

Versions

RepositoryScoreLicence
This page · joeblackwaslike/agent-skills100MIT
wolfinApp/wolfin-senior100MIT
Cynnamoroll/factory-stack90MIT
johantor/brain86Apache-2.0
voyager67/Agent-Workbench86MIT
ericwang200608-beep/LANYANT-Skills85MIT
jstarfilms/vibecode-protocol-suite85ISC

Database snapshot: 13.11.2026 · package version 8fd9805760cc (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

  • 100design-patterns
    Use when picking or implementing a named pattern: Strategy, Observer, Adapter, Decorator, Factory, Repository, Unit of Work, Dependency injection, Retry with backoff, Circuit Breaker, Idempotency key, Outbox, Result type. Not for whether to abstract at all (use…
  • 100clean-code-principles
    SOLID principles, design patterns, DRY, KISS, and clean code fundamentals. Use when reviewing architecture, checking code quality, refactoring, or discussing design decisions. Triggers on "review architecture", "check code quality", "SOLID principles", "design patterns", or "clean code".
  • 100code-architectures
    Use when choosing or structuring how a system is built: hexagonal layering, CQRS, event sourcing, event-driven design, sagas, microservices vs monolith, strangler-fig migration, service timeouts and contracts, CAP and eventual consistency. Not for aggregates or bounded contexts…
  • 100solid-principles-code-review-compliance
    Use this skill when review object-oriented architectures for compliance with SOLID software design principles.
  • 100solid-principles
    Audits code for adherence to the five SOLID principles and reports violations with concrete fixes. Use when reviewing class design, dependency structure, or object-oriented quality.
  • 100solid-review
    SOLID design-principles review (SRP / OCP / LSP / ISP / DIP) on a file/directory/glob. Review-only. Triggers on `/solid-review`, \"SOLID review\", \"design review\", \"design principles\", \"SOLID 검증\", \"디자인 리뷰\", \"원칙 검증\", or `/deep-test` running it as the Advisory Gate.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.