library-craft

name	library-craft
description	Reviews reusable package craft: third-party dependencies, exports, layout, naming, tests, docs, compatibility, and release shape. Use for npm packages, SDKs, framework utilities, reusable modules, or public APIs.

Library Craft

Quick Start

Use this skill when the work affects a reusable package, public API, package exports, or maintainer-facing source organization.

Example trigger: library-craft this package before we publish

Default posture: analysis first. Do not edit source files unless the user explicitly asks to implement.

Default scope: review the whole library contract unless the user gives a narrower scope.

Breaking changes are welcome when they make the library cleaner, smaller, or more honest. If the user opts out of breaking changes, preserve compatibility and name the trade-off.

Workflow

1. Identify the package, public entrypoints, consumer contract, and whether breaking changes are allowed.
2. Read package metadata, dependency and lockfile state, export maps, source entrypoints, build config, tests, fixtures, README/docs, examples, and release notes.
3. Separate the public surface from internal shape.
4. Review the craft lenses:
   • surface - exports, subpaths, types, defaults, runtime guarantees.
   • dependencies - third-party contract fit, public leakage, runtime and module pressure, bundling, maintenance, and replacement cost.
   • shape - folders, helpers, generated files, fixtures, build output.
   • names - user-facing concepts, options, files, helpers.
   • tests - public API, fixtures, examples, type tests, regression checks.
   • comments - public docs, rationale, compatibility notes, noisy narration.
   • release - semver impact, migration path, shims, deprecations.
5. Load references/principles.md for the review vocabulary.
6. For serious public-surface decisions, recommend focused ecosystem comparison. Load references/ecosystem-comparison.md before proposing large dependency, API, export, compatibility, or release-shape changes.
7. Load references/report-shape.md before writing the final aggressive report.

Action Labels

• keep - preserve a pattern that is earning its cost.
• rename - a name hides the concept or leaks implementation.
• move - file or folder placement fights the scan path.
• narrow - public surface or options are broader than needed.
• split - one entrypoint or file owns multiple public concepts.
• merge - separation creates ceremony without a real concept.
• comment - comments are missing, stale, noisy, or API-significant.
• test - contract, fixture, type, or example coverage is missing.
• break - compatibility is making the package worse.

For every break, include what breaks, why it is worth it, the migration path, and whether a compatibility shim should exist.

Rules

• Keep keep short; spend most of the report on pressure.
• Treat package.json exports, README examples, and generated types as API.
• Treat third-party dependencies as package contract pressure when they affect public types, runtime or module support, transitive surface, bundling, install or startup cost, maintenance, license or security posture, replacement cost, or release shape.
• Use a dependency directly while localized. Add an adapter only when it protects a stable public or core contract from a volatile API, normalizes multiple implementations, or contains a real runtime boundary.
• Comments explain why; they do not narrate what the code already says.
• Do not invent a new taxonomy when the package already has a clear local pattern.
• If the issue is really module depth, seam design, or locality, hand off to codebase-design.
• If naming changes affect project language, say so and suggest grill-with-docs; do not update project context by default.
• Do not publish comments, issues, releases, or PR notes without explicit user consent.