Encapsulating Complexity

Hide implementation details behind interfaces - work at domain level (what), not implementation level (how)

43 stars 26 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add obra/clank --skill Encapsulating Complexity
Manual install
git clone --depth 1 https://github.com/obra/clank.git /tmp/clank
mkdir -p ~/.claude/skills
cp -r /tmp/clank/skills/architecture/encapsulating-complexity ~/.claude/skills/Encapsulating-Complexity

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Encapsulating Complexity

## Overview

Hide HOW things work. Expose only WHAT they do. Work at domain level (Users, Orders, Config), not implementation level (dicts, SQL rows, JSON files).

**Core principle:** The point of encapsulation is to create possibilities (many ways to implement) and restrict possibilities (one way to use). Implementation details hidden = free to change implementation without breaking clients.

**Violating the letter of this rule is violating the spirit of information hiding.**

## When to Use

**Apply to every class and interface:**
- Designing new classes/modules
- Creating public APIs
- Reviewing code for abstraction leaks
- Refactoring to improve maintainability

**Warning signs you're violating encapsulation:**
- Client code knows storage format (JSON, SQL, files)
- Interface exposes database/file operations
- Returns raw dicts/rows instead of domain objects
- Client code constructs SQL queries or file paths
- Changing from JSON to YAML breaks client code
- Switching databases requires changing all callers
- Tests must know internal data structures
- Method names reveal implementation (saveToJSON, queryDatabase)
- Public fields exposing internal state

## The Encapsulation Test

**Ask these questions about every public method/field:**

1. **Does the interface expose HOW or WHAT?**
   - "Get user" = WHAT (good)
   - "SELECT * FROM users" = HOW (bad)

2. **Can I change implementation without breaking clients?**
   - JSON → YAML: should work
Read the full skill on GitHub

Details

Skill name
Encapsulating Complexity
Repository
obra/clank
Path
skills/architecture/encapsulating-complexity/SKILL.md
Repo updated
9 October 2025

FAQ

What does the Encapsulating Complexity skill do?

Hide implementation details behind interfaces - work at domain level (what), not implementation level (how)

How do I install the Encapsulating Complexity skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add obra/clank --skill Encapsulating Complexity. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Encapsulating Complexity popular?

It lives in obra/clank, which has 43 GitHub stars and 26 forks.

Related skills

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.