relay: Skill for Claude Code

You fix one pattern: a TypeScript object type manually mirrors a runtime object that already owns the shape.

Prefer value-first APIs. Build the object in a named factory, then export type X = ReturnType<typeof makeX>. Consumers keep importing the stable type name, but the type cannot drift from the implementation.

Trace before changing

1. Find the source value. Look for an object returned from a named factory, extension: (...) => ({ ... }), a client object, route map, or handler table.
2. Find the duplicate type. A nearby interface X or type X = { ... } repeats the object methods/properties.
3. Check whether the value is the source of truth. If the interface is a contract with multiple implementations, keep the interface.
4. Preserve the exported type name. Replace its definition with ReturnType<typeof makeX> and update callers only if needed.
5. Use satisfies only at boundaries. Do not make the implementation satisfy a duplicate shape that could drift.

Fix shape

const makePluginExtension = (ctx: PluginCtx<Store>) => {
  const addSource = ...
  const removeSource = ...

  return {
    addSource,
    removeSource,
  };
};

export type PluginExtension = ReturnType<typeof makePluginExtension>;

For factories that need options:

const makePluginExtension =
  (options: PluginOptions) =>
  (ctx: PluginCtx<Store>) => ({
    addSource: ...,
  });

export type PluginExtension = ReturnType<ReturnType<typeof makePluginExtension>>;

Bad

export interface McpPluginExtension {
  readonly addSource: (config: McpSourceConfig) => Effect.Effect<AddResult, Failure>;
  readonly removeSource: (namespace: string, scope: string) => Effect.Effect<void, Failure>;
}

extension: (ctx) => {
  return {
    addSource,
    removeSource,
  } satisfies McpPluginExtension;
};

Good

const makeMcpPluginExtension = (ctx: PluginCtx<McpStore>) => {
  return {
    addSource,
    removeSource,
  };
};

export type McpPluginExtension = ReturnType<typeof makeMcpPluginExtension>;

extension: makeMcpPluginExtension;