How do I install the API Surface Minimalism skill?

Run npx skillmds@latest add amey-thakur/api-surface-minimalism in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is API Surface Minimalism safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with API Surface Minimalism?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is API Surface Minimalism free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published API Surface Minimalism?

Amey-Thakur (@amey-thakur) published this skill. Their other Agent Skills are listed on their SkillMD profile.

API Surface Minimalism by amey-thakur

Name: API Surface Minimalism
Author: Amey-Thakur

API Surface Minimalism

Keep the public API small by defaulting to private visibility and retiring symbols through deprecation before deletion. Use when designing a module's exports or reviewing what a package exposes to callers.

Amey-Thakur 70d4d9d 2.5 KB Updated Sep 17, 2026

File contents

API surface minimalism

Every exported symbol is a promise you maintain until you break it, and callers bind to whatever you expose whether or not you meant them to. A wide surface is expensive forever: it constrains refactors, multiplies test burden, and turns internal details into contracts. The method is to expose the minimum callers need and to withdraw capability on a schedule, never by surprise.

Method

Default every symbol to private. Start at the language's tightest visibility: private, an unexported lowercase name in Go, no __all__ entry in Python. Widen only when a concrete caller needs it. Export on demand.
Publish one entry point per module. Funnel access through a single index or facade so internal file structure stays free to change. Callers importing deep paths like pkg/internal/impl/thing freeze your layout in place.
Prefer functions over exposed data. Return a value or accessor instead of an exported mutable object or field. An exported field is a two-way contract; a getter lets you change the representation behind it later.
Gate new surface behind its own review. Treat "add to public API" as a decision distinct from the feature. Ask whether it could ship internal first and graduate to public once a second caller actually appears.
Deprecate before you delete. Mark the old symbol with @Deprecated, warnings.warn(DeprecationWarning), or a doc note stating the replacement and the removal version. Keep it working at least one minor release.
Delete on a published cadence. Remove deprecated symbols only at a major version or an announced window, and record each in the changelog. Silent removal turns a routine upgrade into an outage for someone downstream.

Checks

Grep the exports: can you name a caller outside the module for each one?
Does removing a symbol force a major bump, or did it never reach release notes?
For each deprecation, are the replacement and removal version stated together?

Boundaries

Libraries under a strict semantic-versioning contract set the real rules here: follow the project's stability policy over personal taste. Internal code with a single consumer can be looser, and framework plugin points sometimes must expose more than feels comfortable.

---name: api-surface-minimalismdescription: Keep the public API small by defaulting to private visibility and retiring symbols through deprecation before deletion. Use when designing a module's exports or reviewing what a package exposes to callers.---# API surface minimalismEvery exported symbol is a promise you maintain until you break it, and callersbind to whatever you expose whether or not you meant them to. A wide surface isexpensive forever: it constrains refactors, multiplies test burden, and turnsinternal details into contracts. The method is to expose the minimum callersneed and to withdraw capability on a schedule, never by surprise.## Method1. **Default every symbol to private.** Start at the language's tightest visibility: `private`, an unexported lowercase name in Go, no `__all__` entry in Python. Widen only when a concrete caller needs it. Export on demand.2. **Publish one entry point per module.** Funnel access through a single index or facade so internal file structure stays free to change. Callers importing deep paths like `pkg/internal/impl/thing` freeze your layout in place.3. **Prefer functions over exposed data.** Return a value or accessor instead of an exported mutable object or field. An exported field is a two-way contract; a getter lets you change the representation behind it later.4. **Gate new surface behind its own review.** Treat "add to public API" as a decision distinct from the feature. Ask whether it could ship internal first and graduate to public once a second caller actually appears.5. **Deprecate before you delete.** Mark the old symbol with `@Deprecated`, `warnings.warn(DeprecationWarning)`, or a doc note stating the replacement and the removal version. Keep it working at least one minor release.6. **Delete on a published cadence.** Remove deprecated symbols only at a major version or an announced window, and record each in the changelog. Silent removal turns a routine upgrade into an outage for someone downstream.## Checks- Grep the exports: can you name a caller outside the module for each one?- Does removing a symbol force a major bump, or did it never reach release notes?- For each deprecation, are the replacement and removal version stated together?## BoundariesLibraries under a strict semantic-versioning contract set the real rules here:follow the project's stability policy over personal taste. Internal code with asingle consumer can be looser, and framework plugin points sometimes mustexpose more than feels comfortable.

Frequently asked questions