maintainable-typescript

Name: maintainable-typescript
Author: miguelspizza

github.com/miguelspizzaDevelopment12109 installsUpdated 2w ago

About maintainable-typescript

A skill for maintaining and reviewing TypeScript projects through task-specific guidance on structure, types, testing, and tooling. It includes an audit workflow and recommends Fallow for code health checks.

Key features

01Task-based guidance routing
02Repository audit workflow
03Type and API design principles
04Testing and boundary practices
05Fallow code health checks

Use cases

01Review a TypeScript repository
02Remove obsolete code
03Plan module and package boundaries
04Improve tests and type design

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/miguelspizza/skills --skill maintainable-typescript

After installing, type/maintainable-typescriptin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/tooling-templates/

.fallowrc.json

doctrine/abstractions/

build-deep-modules-not-shallow-abstractions.md

compose-behavior-do-not-specialize-classes.md

design-around-composable-primitives.md

keep-a-functional-core-and-imperative-shell.md

keep-schemas-minimal.md

make-builders-earn-their-keep.md

no-premature-abstractions.md

ssot-or-die.md

structure-typescript-apps-around-feature-owners.md

use-classes-for-object-apis-not-service-buckets.md

doctrine/boundaries/

assign-cache-invalidation-owners.md

boundaries-validate-internals-trust.md

error-messages-are-ux.md

log-at-boundaries-not-everywhere.md

no-defensive-catches.md

no-defensive-null-checks.md

no-type-casts.md

pass-values-across-boundaries.md

doctrine/deletion/

clean-up-what-you-touch.md

delete-fake-layers.md

delete-obsolete-code.md

edit-real-owners.md

no-backwards-compat-shims.md

doctrine/foundations/

atomic-changes.md

bounded-behavior.md

comments-say-why-not-what.md

commit-messages-describe-why.md

maintainability-equals-correctness.md

naming-is-navigation.md

Details

From the project README

Maintainable TypeScript

Use this skill when the project needs maintainability doctrine, not just local code changes.

Load Order

Do not read the whole skill directory by default.

Read this file first.
Load only files that match the task.
If the repo matches the house stack, read stack/start-here.md.
Treat doctrine/, stack/, prompts/, scripts/, and assets/tooling-templates/ as references, not required context.

Companion Skills

Use the fallow skill for Fallow config, commands, JSON output, fixes, CI gates, and result interpretation. If missing:

npx skills add https://github.com/fallow-rs/fallow/tree/main/npm/fallow/skills/fallow --skill fallow

Task Router

Backbone: maintainability-equals-correctness, resolve-uncertainty-into-contracts, ssot-or-die, integration-first-testing, external-boundary-mocks-only, assert-observable-outcomes
Cleanup/refactor: clean-up-what-you-touch, delete-obsolete-code, no-backwards-compat-shims, delete-fake-layers, edit-real-owners, build-deep-modules-not-shallow-abstractions, cleanup-module-rewrite, review-structural-slop
Packages/boundaries: structure-typescript-apps-around-feature-owners, monorepo-package-boundaries, treat-critical-code-like-a-library, naming-is-navigation, no-re-exports, no-barrel-exports
Stack/API/types: stack-overview, design-openapi-for-inference, errors-are-schema, document-fields-in-derived-zod-schemas, use-canonical-named-types, jsdoc-with-first-party-sources, no-magic-values, use-branded-scalar-types
Testing/frontend/tooling: contract-gate-synthetic-fixtures, test-ai-apps-by-artifacts-not-prose, no-type-casts, boundaries-validate-internals-trust, do-not-synchronize-state-with-useeffect, use-the-design-system-not-ad-hoc-tailwind, test-react-apps-in-real-browsers, maintainability-tooling
Editing this skill: read the files you touch, then run the bundled verification scripts.

Audit workflow

For cleanup or review:

skill_dir="<path-to-this-skill>"
bash "$skill_dir/scripts/audit-typescript-repo.sh" .

Treat audit output as signal, not authority. Check real usage before deleting API surface or collapsing a pattern.

If the target repo is Vite+, use vp for the normal toolchain entrypoint: vp lint, vp test, vp fmt, vp pack, vp add, and vp dlx.

Defaults

Structure is expensive; preserve contracts, tests, and invariants.
Prefer deletion over shims, real owners over fake layers, and stable subsystem files over helper forests.
Resolve uncertainty into contracts, not adapters, defaults, optionals, spreads, or catches.
Prefer derived types/schemas, durable integration tests, external-boundary mocks only, and assertions on observable outcomes.
Prefer Fallow for dead code, duplication, dependency hygiene, health, cycles, and dependency boundaries.
Leave the codebase more coherent now.

Comments

Markdown supported

Details

Author: miguelspizza
Repository: miguelspizza/skills
Category: Development
Installs: 109
GitHub stars: 12

Report

More skills

All skills

remotion-render

github.com/inference-sh

1.6M

Render videos from React/Remotion component code via inference.sh. Pass TSX code, get MP4. Supports all Remotion APIs: useCurrentFrame, useVideoConfig, spring, interpolate, AbsoluteFill, Sequence. Configurable resolution, FPS, duration, codec. Use for: programmatic video generation, animated graphics, motion design, data-driven videos, React animations to video. Triggers: remotion, render video from code, tsx to video, react video, programmatic video, remotion render, code to video, animated video, motion graphics code, react animation video

improve-codebase-architecture

github.com/mattpocock

1.2M

Scan a codebase for architecture improvement opportunities, present them as a visual HTML report, then dive deep into whichever one you pick.

design-mobile-apps

github.com/designed-by-ai

1.1M

Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML

vercel-react-best-practices

github.com/vercel-labs

848.6k

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.