Claude Code Plugins

Community-maintained marketplace

Feedback

kubit-designing-api

@aniftyco/kubit
32
0

Use when adding new API surface, modifying existing APIs, or defining TypeScript types for framework features. Use when discussing method signatures, return types, decorator APIs, or module exports.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name kubit-designing-api
description Use when adding new API surface, modifying existing APIs, or defining TypeScript types for framework features. Use when discussing method signatures, return types, decorator APIs, or module exports.

Designing Kubit APIs

Overview

Design APIs by starting with ideal usage in skeleton/, then codifying as types in packages/core/, then documenting in SPEC.md.

When to Use

  • Adding new method, decorator, or export to framework
  • Modifying existing API signatures
  • Defining types in packages/core/*.d.ts
  • User asks "how should this API look?"

API Design Flow

digraph api_flow {
  "Write usage in skeleton/" -> "Add types to packages/core/" -> "Document in SPEC.md" -> "Verify tsc passes";
}
  1. Usage First: Write the ideal developer experience in skeleton/
  2. Types Second: Add ambient types to make it compile
  3. Spec Third: Document with TypeScript signatures
  4. Verify: Run tsc --noEmit in skeleton/

Design Principles

Principle Application
DX First How does this feel to use? Start from skeleton.
Type Safety Can TypeScript catch mistakes at compile time?
Conventions Follow Laravel/Rails patterns where sensible
Minimal API Smallest surface that solves the problem
Extensibility Can users extend without modifying core?

Patterns in Use

Decorators: @column(), @before(), @property(), @use() - metadata on classes/properties

Method Chaining: router.get('/').name('home') - fluent API for configuration

Controller Tuples: [Controller, 'method'] - type-safe handler references

Lazy Relations: @hasMany(() => Post) - arrow function to avoid circular deps

Static Dispatch: Job.dispatch({}), Mailable.send({}) - class-level entry points

Type Definition Location

All public types go in packages/core/:

File Contents
kubit.d.ts defineConfig, env, use
router.d.ts router object, handler types
orm.d.ts Model, column decorators, relations
queue.d.ts Job, @property
mail.d.ts Mailable
db.d.ts Migration, schema
inertia.d.ts view()
http.d.ts HttpContext
hash.d.ts hash()

Checklist Before Adding API

  • Usage example exists in skeleton/
  • Types added to packages/core/
  • tsc --noEmit passes in skeleton/
  • SPEC.md updated with TypeScript signature
  • Follows existing patterns (decorators, chaining, etc.)